@galacean/engine-ui 2.0.0-alpha.46 → 2.0.0-alpha.48

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/browser.js CHANGED
@@ -113,13 +113,17 @@
113
113
  }
114
114
  return this._globalInteractive;
115
115
  };
116
- _proto._onEnableInScene = function _onEnableInScene() {
116
+ /**
117
+ * @internal
118
+ */ _proto._onEnableInScene = function _onEnableInScene() {
117
119
  Utils.setRootCanvasDirty(this);
118
120
  Utils.setGroupDirty(this);
119
121
  // @ts-ignore
120
122
  this.entity._dispatchModify(EntityUIModifyFlags.GroupEnableInScene);
121
123
  };
122
- _proto._onDisableInScene = function _onDisableInScene() {
124
+ /**
125
+ * @internal
126
+ */ _proto._onDisableInScene = function _onDisableInScene() {
123
127
  Utils.cleanRootCanvas(this);
124
128
  Utils.cleanGroup(this);
125
129
  var disorderedElements = this._disorderedElements;
@@ -569,14 +573,16 @@
569
573
  }({});
570
574
 
571
575
  /**
572
- * Resolution adaptation mode.
573
- * @remarks Only effective in screen space.
576
+ * Resolution adaptation in screen space.
577
+ * Scale ratios are available size / `referenceResolution` per axis.
578
+ * Available size comes from the canvas in Overlay mode or the camera's standard projection at `distance`
579
+ * in Camera mode; a custom `Camera.projectionMatrix` is not reflected.
574
580
  */ var ResolutionAdaptationMode = /*#__PURE__*/ function(ResolutionAdaptationMode) {
575
581
  /** Adapt based on width.(`referenceResolution.x`) */ ResolutionAdaptationMode[ResolutionAdaptationMode["WidthAdaptation"] = 0] = "WidthAdaptation";
576
582
  /** Adapt based on height.(`referenceResolution.y`) */ ResolutionAdaptationMode[ResolutionAdaptationMode["HeightAdaptation"] = 1] = "HeightAdaptation";
577
583
  /** Adapt based on both width and height.(`referenceResolution`) */ ResolutionAdaptationMode[ResolutionAdaptationMode["BothAdaptation"] = 2] = "BothAdaptation";
578
- /** Adapt to the side with a larger ratio. */ ResolutionAdaptationMode[ResolutionAdaptationMode["ExpandAdaptation"] = 3] = "ExpandAdaptation";
579
- /** Adapt to the side with smaller ratio. */ ResolutionAdaptationMode[ResolutionAdaptationMode["ShrinkAdaptation"] = 4] = "ShrinkAdaptation";
584
+ /** Use the smaller scale ratio to fit the reference rectangle; the UICanvas expands on the other axis. */ ResolutionAdaptationMode[ResolutionAdaptationMode["ExpandAdaptation"] = 3] = "ExpandAdaptation";
585
+ /** Use the larger scale ratio to cover the available area; the reference rectangle may overflow. */ ResolutionAdaptationMode[ResolutionAdaptationMode["ShrinkAdaptation"] = 4] = "ShrinkAdaptation";
580
586
  return ResolutionAdaptationMode;
581
587
  }({});
582
588
 
@@ -621,6 +627,7 @@
621
627
  this._updateWorldFlagWithParentRectChange(engine.TransformModifyFlags.WmWpWeWqWsWus);
622
628
  };
623
629
  /**
630
+ * @internal
624
631
  * @inheritdoc
625
632
  */ _proto._onClone = function _onClone(target) {
626
633
  Transform.prototype._onClone.call(this, target);
@@ -777,7 +784,8 @@
777
784
  {
778
785
  key: "size",
779
786
  get: /**
780
- * Width and height of UI element.
787
+ * Width and height in local units, before transform scaling.
788
+ * Screen-space units are pixels at the root canvas's {@link UICanvas.referenceResolution}; world-space units are scene units.
781
789
  */ function get() {
782
790
  return this._size;
783
791
  },
@@ -1019,17 +1027,25 @@
1019
1027
  return _this;
1020
1028
  }
1021
1029
  var _proto = UIRenderer.prototype;
1022
- _proto._canBatch = function _canBatch(preElement, curElement) {
1030
+ /**
1031
+ * @internal
1032
+ */ _proto._canBatch = function _canBatch(preElement, curElement) {
1023
1033
  return engine.VertexMergeBatcher.canBatchSprite(preElement, curElement);
1024
1034
  };
1025
- _proto._batch = function _batch(preElement, curElement) {
1035
+ /**
1036
+ * @internal
1037
+ */ _proto._batch = function _batch(preElement, curElement) {
1026
1038
  engine.VertexMergeBatcher.batch(preElement, curElement);
1027
1039
  };
1028
- _proto._updateTransformShaderData = function _updateTransformShaderData(context, onlyMVP) {
1040
+ /**
1041
+ * @internal
1042
+ */ _proto._updateTransformShaderData = function _updateTransformShaderData(context, onlyMVP) {
1029
1043
  // @ts-ignore
1030
1044
  this._updateWorldSpaceTransformShaderData(context, onlyMVP);
1031
1045
  };
1032
- _proto._prepareRender = function _prepareRender(context) {
1046
+ /**
1047
+ * @internal
1048
+ */ _proto._prepareRender = function _prepareRender(context) {
1033
1049
  // Update once per frame per renderer, not influenced by batched
1034
1050
  if (this._renderFrameCount !== this.engine.time.frameCount) {
1035
1051
  this._update(context);
@@ -1038,13 +1054,17 @@
1038
1054
  // union camera global macro and renderer macro.
1039
1055
  engine.ShaderMacroCollection.unionCollection(context.camera._globalShaderMacro, this.shaderData._macroCollection, this._globalShaderMacro);
1040
1056
  };
1041
- _proto._onEnableInScene = function _onEnableInScene() {
1057
+ /**
1058
+ * @internal
1059
+ */ _proto._onEnableInScene = function _onEnableInScene() {
1042
1060
  this._overrideUpdate && this.scene._componentsManager.addOnUpdateRenderers(this);
1043
1061
  this.entity._updateUIHierarchyVersion(exports.UICanvas._hierarchyCounter);
1044
1062
  Utils.setRootCanvasDirty(this);
1045
1063
  Utils.setGroupDirty(this);
1046
1064
  };
1047
- _proto._onDisableInScene = function _onDisableInScene() {
1065
+ /**
1066
+ * @internal
1067
+ */ _proto._onDisableInScene = function _onDisableInScene() {
1048
1068
  this._overrideUpdate && this.scene._componentsManager.removeOnUpdateRenderers(this);
1049
1069
  this.entity._updateUIHierarchyVersion(exports.UICanvas._hierarchyCounter);
1050
1070
  Utils.cleanRootCanvas(this);
@@ -1106,7 +1126,6 @@
1106
1126
  /**
1107
1127
  * @internal
1108
1128
  */ _proto._raycast = function _raycast(ray, out, distance) {
1109
- if (distance === void 0) distance = Number.MAX_SAFE_INTEGER;
1110
1129
  var plane = UIRenderer._tempPlane;
1111
1130
  var transform = this._transformEntity.transform;
1112
1131
  var normal = plane.normal.copyFrom(transform.worldForward);
@@ -1311,13 +1330,17 @@
1311
1330
  this._isGroupDirty && Utils.setGroup(this, Utils.searchGroupInParents(this));
1312
1331
  return this._group;
1313
1332
  };
1314
- _proto._onEnableInScene = function _onEnableInScene() {
1333
+ /**
1334
+ * @internal
1335
+ */ _proto._onEnableInScene = function _onEnableInScene() {
1315
1336
  Script.prototype._onEnableInScene.call(this);
1316
1337
  Utils.setRootCanvasDirty(this);
1317
1338
  Utils.setGroupDirty(this);
1318
1339
  this._updateState(true);
1319
1340
  };
1320
- _proto._onDisableInScene = function _onDisableInScene() {
1341
+ /**
1342
+ * @internal
1343
+ */ _proto._onDisableInScene = function _onDisableInScene() {
1321
1344
  Script.prototype._onDisableInScene.call(this);
1322
1345
  Utils.cleanRootCanvas(this);
1323
1346
  Utils.cleanGroup(this);
@@ -1473,12 +1496,11 @@
1473
1496
  var _proto = UICanvas.prototype;
1474
1497
  /**
1475
1498
  * @internal
1476
- */ _proto._raycast = function _raycast(ray, out, distance) {
1477
- if (distance === void 0) distance = Number.MAX_SAFE_INTEGER;
1499
+ */ _proto._raycast = function _raycast(ray, out, distance, cullingMask) {
1478
1500
  var renderers = this._getRenderers();
1479
1501
  for(var i = renderers.length - 1; i >= 0; i--){
1480
1502
  var element = renderers[i];
1481
- if (element.raycastEnabled && element._raycast(ray, out, distance)) {
1503
+ if ((cullingMask & element.entity.layer) !== 0 && element.raycastEnabled && element._raycast(ray, out, distance)) {
1482
1504
  return true;
1483
1505
  }
1484
1506
  }
@@ -1502,10 +1524,12 @@
1502
1524
  /**
1503
1525
  * @internal
1504
1526
  */ _proto._canDispatchEvent = function _canDispatchEvent(camera) {
1505
- var realMode = this._realRenderMode;
1506
- if (realMode === CanvasRenderMode.ScreenSpaceOverlay) {
1527
+ if (this._realRenderMode === CanvasRenderMode.ScreenSpaceOverlay) {
1507
1528
  return true;
1508
1529
  }
1530
+ if (!(camera.cullingMask & this.entity.layer)) {
1531
+ return false;
1532
+ }
1509
1533
  var assignedCamera = this._camera;
1510
1534
  // @ts-ignore
1511
1535
  return !assignedCamera || !assignedCamera._phasedActiveInScene || assignedCamera === camera;
@@ -1524,11 +1548,9 @@
1524
1548
  var renderers = this._getRenderers();
1525
1549
  for(var i = 0, n = renderers.length; i < n; i++){
1526
1550
  var renderer = renderers[i];
1527
- // Filter by camera culling mask
1528
1551
  if (!(cullingMask & renderer.entity.layer)) {
1529
1552
  continue;
1530
1553
  }
1531
- // Filter by camera frustum
1532
1554
  if (enableFrustumCulling) {
1533
1555
  switch(mode){
1534
1556
  case CanvasRenderMode.ScreenSpaceOverlay:
@@ -1578,7 +1600,9 @@
1578
1600
  break;
1579
1601
  }
1580
1602
  };
1581
- _proto._onEnableInScene = function _onEnableInScene() {
1603
+ /**
1604
+ * @internal
1605
+ */ _proto._onEnableInScene = function _onEnableInScene() {
1582
1606
  var entity = this.entity;
1583
1607
  // @ts-ignore
1584
1608
  entity._dispatchModify(4, this);
@@ -1586,11 +1610,15 @@
1586
1610
  this._setIsRootCanvas(!rootCanvas);
1587
1611
  Utils.setRootCanvas(this, rootCanvas);
1588
1612
  };
1589
- _proto._onDisableInScene = function _onDisableInScene() {
1613
+ /**
1614
+ * @internal
1615
+ */ _proto._onDisableInScene = function _onDisableInScene() {
1590
1616
  this._setIsRootCanvas(false);
1591
1617
  Utils.cleanRootCanvas(this);
1592
1618
  };
1593
- _proto._onDisable = function _onDisable() {
1619
+ /**
1620
+ * @internal
1621
+ */ _proto._onDisable = function _onDisable() {
1594
1622
  this._renderElements.length = 0;
1595
1623
  this._batchedRenderElements.length = 0;
1596
1624
  };
@@ -1615,6 +1643,7 @@
1615
1643
  }
1616
1644
  };
1617
1645
  /**
1646
+ * @internal
1618
1647
  * @inheritdoc
1619
1648
  */ _proto._onClone = function _onClone(target) {
1620
1649
  target.renderMode = this._renderMode;
@@ -1869,7 +1898,8 @@
1869
1898
  {
1870
1899
  key: "referenceResolutionPerUnit",
1871
1900
  get: /**
1872
- * The conversion ratio between reference resolution and unit for UI elements in this canvas.
1901
+ * Local UI units per sprite world unit for sliced borders and tile sizing.
1902
+ * One glyph pixel maps to `referenceResolutionPerUnit / 100` local UI units.
1873
1903
  */ function get() {
1874
1904
  return this._referenceResolutionPerUnit;
1875
1905
  },
@@ -1885,7 +1915,8 @@
1885
1915
  {
1886
1916
  key: "referenceResolution",
1887
1917
  get: /**
1888
- * The reference resolution of the UI canvas in `ScreenSpaceCamera` and `ScreenSpaceOverlay` mode.
1918
+ * Design resolution in pixels for {@link CanvasRenderMode.ScreenSpaceCamera} and {@link CanvasRenderMode.ScreenSpaceOverlay}.
1919
+ * The root canvas adapts it to the camera viewport or engine canvas using {@link UICanvas.resolutionAdaptationMode}.
1889
1920
  */ function get() {
1890
1921
  return this._referenceResolution;
1891
1922
  },
@@ -1973,7 +2004,7 @@
1973
2004
  {
1974
2005
  key: "sortOrder",
1975
2006
  get: /**
1976
- * The rendering order priority of the UI canvas in `ScreenSpaceOverlay` mode.
2007
+ * The rendering priority of the canvas.
1977
2008
  */ function get() {
1978
2009
  return this._sortOrder;
1979
2010
  },
@@ -2136,6 +2167,7 @@
2136
2167
  }
2137
2168
  };
2138
2169
  /**
2170
+ * @internal
2139
2171
  * @inheritdoc
2140
2172
  */ _proto._onClone = function _onClone(target) {
2141
2173
  UIRenderer1.prototype._onClone.call(this, target);
@@ -2745,7 +2777,9 @@
2745
2777
  {
2746
2778
  key: "fontSize",
2747
2779
  get: /**
2748
- * The font size of the Text.
2780
+ * Font size in pixels, used for glyph rasterization.
2781
+ * Glyph pixel dimensions are converted to local UI units using the root canvas's
2782
+ * {@link UICanvas.referenceResolutionPerUnit}.
2749
2783
  */ function get() {
2750
2784
  return this._fontSize;
2751
2785
  },
@@ -2934,6 +2968,7 @@
2934
2968
  this._target = null;
2935
2969
  };
2936
2970
  /**
2971
+ * @internal
2937
2972
  * @inheritdoc
2938
2973
  */ _proto._onClone = function _onClone(target) {
2939
2974
  target._addStateValuesReferCount(1);
@@ -3272,13 +3307,12 @@
3272
3307
  var scene = scenes[i];
3273
3308
  if (!scene.isActive || scene.destroyed) continue;
3274
3309
  var componentsManager = scene._componentsManager;
3275
- // Overlay Canvas
3276
3310
  var canvasElements = componentsManager._overlayCanvases;
3277
- // Screen to world ( Assume that world units have a one-to-one relationship with pixel units )
3311
+ // Convert screen coordinates to overlay coordinates.
3278
3312
  ray.origin.set(position.x, scene.engine.canvas.height - position.y, 1);
3279
3313
  ray.direction.set(0, 0, -1);
3280
3314
  for(var j = canvasElements.length - 1; j >= 0; j--){
3281
- if (canvasElements.get(j)._raycast(ray, hitResult)) {
3315
+ if (canvasElements.get(j)._raycast(ray, hitResult, Number.MAX_SAFE_INTEGER, engine.Layer.Everything)) {
3282
3316
  this._updateRaycast(hitResult.component, pointer);
3283
3317
  return;
3284
3318
  }
@@ -3292,26 +3326,22 @@
3292
3326
  continue;
3293
3327
  }
3294
3328
  camera.screenPointToRay(pointer.position, ray);
3295
- // Other canvases
3296
- var isOrthographic = camera.isOrthographic;
3297
- var _camera_entity_transform = camera.entity.transform, cameraPosition = _camera_entity_transform.worldPosition, cameraForward = _camera_entity_transform.worldForward;
3298
- // Sort by rendering order
3299
3329
  canvasElements = componentsManager._canvases;
3330
+ var isOrthographic = camera.isOrthographic, farClipPlane = camera.farClipPlane, cullingMask = camera.cullingMask;
3331
+ var _camera_entity_transform = camera.entity.transform, worldPosition = _camera_entity_transform.worldPosition, worldForward = _camera_entity_transform.worldForward;
3300
3332
  for(var k = 0, n = canvasElements.length; k < n; k++){
3301
- canvasElements.get(k)._updateSortDistance(isOrthographic, cameraPosition, cameraForward);
3333
+ canvasElements.get(k)._updateSortDistance(isOrthographic, worldPosition, worldForward);
3302
3334
  }
3303
- canvasElements.sort(function(a, b) {
3304
- return a.sortOrder - b.sortOrder || a._sortDistance - b._sortDistance;
3305
- });
3335
+ canvasElements.sort(UIPointerEventEmitter._compareRaycastOrder);
3336
+ // Update registry indices after sorting.
3306
3337
  for(var k1 = 0, n1 = canvasElements.length; k1 < n1; k1++){
3307
3338
  canvasElements.get(k1)._canvasIndex = k1;
3308
3339
  }
3309
- var farClipPlane = camera.farClipPlane;
3310
- // Post-rendering first detection
3340
+ // Fully tied canvases may differ in hit and draw order.
3311
3341
  for(var k2 = 0, n2 = canvasElements.length; k2 < n2; k2++){
3312
3342
  var canvas = canvasElements.get(k2);
3313
3343
  if (!canvas._canDispatchEvent(camera)) continue;
3314
- if (canvas._raycast(ray, hitResult, farClipPlane)) {
3344
+ if (canvas._raycast(ray, hitResult, farClipPlane, cullingMask)) {
3315
3345
  this._updateRaycast(hitResult.component, pointer);
3316
3346
  return;
3317
3347
  }
@@ -3472,6 +3502,9 @@
3472
3502
  fireEvent(path[i], eventData);
3473
3503
  }
3474
3504
  };
3505
+ UIPointerEventEmitter._compareRaycastOrder = function _compareRaycastOrder(a, b) {
3506
+ return b.sortOrder - a.sortOrder || a._sortDistance - b._sortDistance;
3507
+ };
3475
3508
  return UIPointerEventEmitter;
3476
3509
  }(engine.PointerEventEmitter);
3477
3510
  exports.UIPointerEventEmitter._MAX_PATH_DEPTH = 2048;
@@ -3483,7 +3516,9 @@
3483
3516
  engine.registerPointerEventEmitter()
3484
3517
  ], exports.UIPointerEventEmitter);
3485
3518
 
3486
- var EngineExtension = /*#__PURE__*/ function() {
3519
+ /**
3520
+ * @internal
3521
+ */ var EngineExtension = /*#__PURE__*/ function() {
3487
3522
  function EngineExtension() {}
3488
3523
  var _proto = EngineExtension.prototype;
3489
3524
  _proto._getUIDefaultMaterial = function _getUIDefaultMaterial() {
@@ -3498,7 +3533,9 @@
3498
3533
  };
3499
3534
  return EngineExtension;
3500
3535
  }();
3501
- var EntityExtension = /*#__PURE__*/ function() {
3536
+ /**
3537
+ * @internal
3538
+ */ var EntityExtension = /*#__PURE__*/ function() {
3502
3539
  function EntityExtension() {
3503
3540
  this._uiHierarchyVersion = 0;
3504
3541
  }