@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/module.js CHANGED
@@ -1,4 +1,4 @@
1
- import { EntityModifyFlags, ignoreClone, DisorderedArray, Component, Matrix, BoundingBox, Utils as Utils$1, TransformModifyFlags, Transform, Vector2, Rect, MathUtil, Vector3, Plane, ShaderProperty, dependentComponents, DependentMode, VertexMergeBatcher, ShaderMacroCollection, Renderer, Vector4, Color, RendererUpdateFlags, Script, CameraModifyFlags, Logger, Signal, SpriteDrawMode, SpriteModifyFlags, SpriteTileMode, TiledSpriteAssembler, SlicedSpriteAssembler, SimpleSpriteAssembler, ShaderData, ShaderDataGroup, TextUtils, Engine, TextVerticalAlignment, TextHorizontalAlignment, OverflowMode, CharRenderInfo, FontStyle, ReferResource, DataObject, registerPointerEventEmitter, PointerEventEmitter, CameraClearFlags, Material, Entity, Loader, Shader } from '@galacean/engine';
1
+ import { EntityModifyFlags, ignoreClone, DisorderedArray, Component, Matrix, BoundingBox, Utils as Utils$1, TransformModifyFlags, Transform, Vector2, Rect, MathUtil, Vector3, Plane, ShaderProperty, dependentComponents, DependentMode, VertexMergeBatcher, ShaderMacroCollection, Renderer, Vector4, Color, RendererUpdateFlags, Script, CameraModifyFlags, Logger, Signal, SpriteDrawMode, SpriteModifyFlags, SpriteTileMode, TiledSpriteAssembler, SlicedSpriteAssembler, SimpleSpriteAssembler, ShaderData, ShaderDataGroup, TextUtils, Engine, TextVerticalAlignment, TextHorizontalAlignment, OverflowMode, CharRenderInfo, FontStyle, ReferResource, DataObject, registerPointerEventEmitter, PointerEventEmitter, Layer, CameraClearFlags, Material, Entity, Loader, Shader } from '@galacean/engine';
2
2
 
3
3
  function _defineProperties(target, props) {
4
4
  for (var i = 0; i < props.length; i++) {
@@ -109,13 +109,17 @@ var UIGroup = /*#__PURE__*/ function(Component) {
109
109
  }
110
110
  return this._globalInteractive;
111
111
  };
112
- _proto._onEnableInScene = function _onEnableInScene() {
112
+ /**
113
+ * @internal
114
+ */ _proto._onEnableInScene = function _onEnableInScene() {
113
115
  Utils.setRootCanvasDirty(this);
114
116
  Utils.setGroupDirty(this);
115
117
  // @ts-ignore
116
118
  this.entity._dispatchModify(EntityUIModifyFlags.GroupEnableInScene);
117
119
  };
118
- _proto._onDisableInScene = function _onDisableInScene() {
120
+ /**
121
+ * @internal
122
+ */ _proto._onDisableInScene = function _onDisableInScene() {
119
123
  Utils.cleanRootCanvas(this);
120
124
  Utils.cleanGroup(this);
121
125
  var disorderedElements = this._disorderedElements;
@@ -565,14 +569,16 @@ var SortEntry = function SortEntry() {
565
569
  }({});
566
570
 
567
571
  /**
568
- * Resolution adaptation mode.
569
- * @remarks Only effective in screen space.
572
+ * Resolution adaptation in screen space.
573
+ * Scale ratios are available size / `referenceResolution` per axis.
574
+ * Available size comes from the canvas in Overlay mode or the camera's standard projection at `distance`
575
+ * in Camera mode; a custom `Camera.projectionMatrix` is not reflected.
570
576
  */ var ResolutionAdaptationMode = /*#__PURE__*/ function(ResolutionAdaptationMode) {
571
577
  /** Adapt based on width.(`referenceResolution.x`) */ ResolutionAdaptationMode[ResolutionAdaptationMode["WidthAdaptation"] = 0] = "WidthAdaptation";
572
578
  /** Adapt based on height.(`referenceResolution.y`) */ ResolutionAdaptationMode[ResolutionAdaptationMode["HeightAdaptation"] = 1] = "HeightAdaptation";
573
579
  /** Adapt based on both width and height.(`referenceResolution`) */ ResolutionAdaptationMode[ResolutionAdaptationMode["BothAdaptation"] = 2] = "BothAdaptation";
574
- /** Adapt to the side with a larger ratio. */ ResolutionAdaptationMode[ResolutionAdaptationMode["ExpandAdaptation"] = 3] = "ExpandAdaptation";
575
- /** Adapt to the side with smaller ratio. */ ResolutionAdaptationMode[ResolutionAdaptationMode["ShrinkAdaptation"] = 4] = "ShrinkAdaptation";
580
+ /** Use the smaller scale ratio to fit the reference rectangle; the UICanvas expands on the other axis. */ ResolutionAdaptationMode[ResolutionAdaptationMode["ExpandAdaptation"] = 3] = "ExpandAdaptation";
581
+ /** Use the larger scale ratio to cover the available area; the reference rectangle may overflow. */ ResolutionAdaptationMode[ResolutionAdaptationMode["ShrinkAdaptation"] = 4] = "ShrinkAdaptation";
576
582
  return ResolutionAdaptationMode;
577
583
  }({});
578
584
 
@@ -617,6 +623,7 @@ var SortEntry = function SortEntry() {
617
623
  this._updateWorldFlagWithParentRectChange(TransformModifyFlags.WmWpWeWqWsWus);
618
624
  };
619
625
  /**
626
+ * @internal
620
627
  * @inheritdoc
621
628
  */ _proto._onClone = function _onClone(target) {
622
629
  Transform.prototype._onClone.call(this, target);
@@ -773,7 +780,8 @@ var SortEntry = function SortEntry() {
773
780
  {
774
781
  key: "size",
775
782
  get: /**
776
- * Width and height of UI element.
783
+ * Width and height in local units, before transform scaling.
784
+ * Screen-space units are pixels at the root canvas's {@link UICanvas.referenceResolution}; world-space units are scene units.
777
785
  */ function get() {
778
786
  return this._size;
779
787
  },
@@ -1015,17 +1023,25 @@ var UIRenderer = /*#__PURE__*/ function(Renderer) {
1015
1023
  return _this;
1016
1024
  }
1017
1025
  var _proto = UIRenderer.prototype;
1018
- _proto._canBatch = function _canBatch(preElement, curElement) {
1026
+ /**
1027
+ * @internal
1028
+ */ _proto._canBatch = function _canBatch(preElement, curElement) {
1019
1029
  return VertexMergeBatcher.canBatchSprite(preElement, curElement);
1020
1030
  };
1021
- _proto._batch = function _batch(preElement, curElement) {
1031
+ /**
1032
+ * @internal
1033
+ */ _proto._batch = function _batch(preElement, curElement) {
1022
1034
  VertexMergeBatcher.batch(preElement, curElement);
1023
1035
  };
1024
- _proto._updateTransformShaderData = function _updateTransformShaderData(context, onlyMVP) {
1036
+ /**
1037
+ * @internal
1038
+ */ _proto._updateTransformShaderData = function _updateTransformShaderData(context, onlyMVP) {
1025
1039
  // @ts-ignore
1026
1040
  this._updateWorldSpaceTransformShaderData(context, onlyMVP);
1027
1041
  };
1028
- _proto._prepareRender = function _prepareRender(context) {
1042
+ /**
1043
+ * @internal
1044
+ */ _proto._prepareRender = function _prepareRender(context) {
1029
1045
  // Update once per frame per renderer, not influenced by batched
1030
1046
  if (this._renderFrameCount !== this.engine.time.frameCount) {
1031
1047
  this._update(context);
@@ -1034,13 +1050,17 @@ var UIRenderer = /*#__PURE__*/ function(Renderer) {
1034
1050
  // union camera global macro and renderer macro.
1035
1051
  ShaderMacroCollection.unionCollection(context.camera._globalShaderMacro, this.shaderData._macroCollection, this._globalShaderMacro);
1036
1052
  };
1037
- _proto._onEnableInScene = function _onEnableInScene() {
1053
+ /**
1054
+ * @internal
1055
+ */ _proto._onEnableInScene = function _onEnableInScene() {
1038
1056
  this._overrideUpdate && this.scene._componentsManager.addOnUpdateRenderers(this);
1039
1057
  this.entity._updateUIHierarchyVersion(UICanvas._hierarchyCounter);
1040
1058
  Utils.setRootCanvasDirty(this);
1041
1059
  Utils.setGroupDirty(this);
1042
1060
  };
1043
- _proto._onDisableInScene = function _onDisableInScene() {
1061
+ /**
1062
+ * @internal
1063
+ */ _proto._onDisableInScene = function _onDisableInScene() {
1044
1064
  this._overrideUpdate && this.scene._componentsManager.removeOnUpdateRenderers(this);
1045
1065
  this.entity._updateUIHierarchyVersion(UICanvas._hierarchyCounter);
1046
1066
  Utils.cleanRootCanvas(this);
@@ -1102,7 +1122,6 @@ var UIRenderer = /*#__PURE__*/ function(Renderer) {
1102
1122
  /**
1103
1123
  * @internal
1104
1124
  */ _proto._raycast = function _raycast(ray, out, distance) {
1105
- if (distance === void 0) distance = Number.MAX_SAFE_INTEGER;
1106
1125
  var plane = UIRenderer._tempPlane;
1107
1126
  var transform = this._transformEntity.transform;
1108
1127
  var normal = plane.normal.copyFrom(transform.worldForward);
@@ -1307,13 +1326,17 @@ UIRenderer = __decorate([
1307
1326
  this._isGroupDirty && Utils.setGroup(this, Utils.searchGroupInParents(this));
1308
1327
  return this._group;
1309
1328
  };
1310
- _proto._onEnableInScene = function _onEnableInScene() {
1329
+ /**
1330
+ * @internal
1331
+ */ _proto._onEnableInScene = function _onEnableInScene() {
1311
1332
  Script.prototype._onEnableInScene.call(this);
1312
1333
  Utils.setRootCanvasDirty(this);
1313
1334
  Utils.setGroupDirty(this);
1314
1335
  this._updateState(true);
1315
1336
  };
1316
- _proto._onDisableInScene = function _onDisableInScene() {
1337
+ /**
1338
+ * @internal
1339
+ */ _proto._onDisableInScene = function _onDisableInScene() {
1317
1340
  Script.prototype._onDisableInScene.call(this);
1318
1341
  Utils.cleanRootCanvas(this);
1319
1342
  Utils.cleanGroup(this);
@@ -1469,12 +1492,11 @@ var UICanvas = /*#__PURE__*/ function(Component) {
1469
1492
  var _proto = UICanvas.prototype;
1470
1493
  /**
1471
1494
  * @internal
1472
- */ _proto._raycast = function _raycast(ray, out, distance) {
1473
- if (distance === void 0) distance = Number.MAX_SAFE_INTEGER;
1495
+ */ _proto._raycast = function _raycast(ray, out, distance, cullingMask) {
1474
1496
  var renderers = this._getRenderers();
1475
1497
  for(var i = renderers.length - 1; i >= 0; i--){
1476
1498
  var element = renderers[i];
1477
- if (element.raycastEnabled && element._raycast(ray, out, distance)) {
1499
+ if ((cullingMask & element.entity.layer) !== 0 && element.raycastEnabled && element._raycast(ray, out, distance)) {
1478
1500
  return true;
1479
1501
  }
1480
1502
  }
@@ -1498,10 +1520,12 @@ var UICanvas = /*#__PURE__*/ function(Component) {
1498
1520
  /**
1499
1521
  * @internal
1500
1522
  */ _proto._canDispatchEvent = function _canDispatchEvent(camera) {
1501
- var realMode = this._realRenderMode;
1502
- if (realMode === CanvasRenderMode.ScreenSpaceOverlay) {
1523
+ if (this._realRenderMode === CanvasRenderMode.ScreenSpaceOverlay) {
1503
1524
  return true;
1504
1525
  }
1526
+ if (!(camera.cullingMask & this.entity.layer)) {
1527
+ return false;
1528
+ }
1505
1529
  var assignedCamera = this._camera;
1506
1530
  // @ts-ignore
1507
1531
  return !assignedCamera || !assignedCamera._phasedActiveInScene || assignedCamera === camera;
@@ -1520,11 +1544,9 @@ var UICanvas = /*#__PURE__*/ function(Component) {
1520
1544
  var renderers = this._getRenderers();
1521
1545
  for(var i = 0, n = renderers.length; i < n; i++){
1522
1546
  var renderer = renderers[i];
1523
- // Filter by camera culling mask
1524
1547
  if (!(cullingMask & renderer.entity.layer)) {
1525
1548
  continue;
1526
1549
  }
1527
- // Filter by camera frustum
1528
1550
  if (enableFrustumCulling) {
1529
1551
  switch(mode){
1530
1552
  case CanvasRenderMode.ScreenSpaceOverlay:
@@ -1574,7 +1596,9 @@ var UICanvas = /*#__PURE__*/ function(Component) {
1574
1596
  break;
1575
1597
  }
1576
1598
  };
1577
- _proto._onEnableInScene = function _onEnableInScene() {
1599
+ /**
1600
+ * @internal
1601
+ */ _proto._onEnableInScene = function _onEnableInScene() {
1578
1602
  var entity = this.entity;
1579
1603
  // @ts-ignore
1580
1604
  entity._dispatchModify(4, this);
@@ -1582,11 +1606,15 @@ var UICanvas = /*#__PURE__*/ function(Component) {
1582
1606
  this._setIsRootCanvas(!rootCanvas);
1583
1607
  Utils.setRootCanvas(this, rootCanvas);
1584
1608
  };
1585
- _proto._onDisableInScene = function _onDisableInScene() {
1609
+ /**
1610
+ * @internal
1611
+ */ _proto._onDisableInScene = function _onDisableInScene() {
1586
1612
  this._setIsRootCanvas(false);
1587
1613
  Utils.cleanRootCanvas(this);
1588
1614
  };
1589
- _proto._onDisable = function _onDisable() {
1615
+ /**
1616
+ * @internal
1617
+ */ _proto._onDisable = function _onDisable() {
1590
1618
  this._renderElements.length = 0;
1591
1619
  this._batchedRenderElements.length = 0;
1592
1620
  };
@@ -1611,6 +1639,7 @@ var UICanvas = /*#__PURE__*/ function(Component) {
1611
1639
  }
1612
1640
  };
1613
1641
  /**
1642
+ * @internal
1614
1643
  * @inheritdoc
1615
1644
  */ _proto._onClone = function _onClone(target) {
1616
1645
  target.renderMode = this._renderMode;
@@ -1865,7 +1894,8 @@ var UICanvas = /*#__PURE__*/ function(Component) {
1865
1894
  {
1866
1895
  key: "referenceResolutionPerUnit",
1867
1896
  get: /**
1868
- * The conversion ratio between reference resolution and unit for UI elements in this canvas.
1897
+ * Local UI units per sprite world unit for sliced borders and tile sizing.
1898
+ * One glyph pixel maps to `referenceResolutionPerUnit / 100` local UI units.
1869
1899
  */ function get() {
1870
1900
  return this._referenceResolutionPerUnit;
1871
1901
  },
@@ -1881,7 +1911,8 @@ var UICanvas = /*#__PURE__*/ function(Component) {
1881
1911
  {
1882
1912
  key: "referenceResolution",
1883
1913
  get: /**
1884
- * The reference resolution of the UI canvas in `ScreenSpaceCamera` and `ScreenSpaceOverlay` mode.
1914
+ * Design resolution in pixels for {@link CanvasRenderMode.ScreenSpaceCamera} and {@link CanvasRenderMode.ScreenSpaceOverlay}.
1915
+ * The root canvas adapts it to the camera viewport or engine canvas using {@link UICanvas.resolutionAdaptationMode}.
1885
1916
  */ function get() {
1886
1917
  return this._referenceResolution;
1887
1918
  },
@@ -1969,7 +2000,7 @@ var UICanvas = /*#__PURE__*/ function(Component) {
1969
2000
  {
1970
2001
  key: "sortOrder",
1971
2002
  get: /**
1972
- * The rendering order priority of the UI canvas in `ScreenSpaceOverlay` mode.
2003
+ * The rendering priority of the canvas.
1973
2004
  */ function get() {
1974
2005
  return this._sortOrder;
1975
2006
  },
@@ -2132,6 +2163,7 @@ var Button = /*#__PURE__*/ function(UIInteractive) {
2132
2163
  }
2133
2164
  };
2134
2165
  /**
2166
+ * @internal
2135
2167
  * @inheritdoc
2136
2168
  */ _proto._onClone = function _onClone(target) {
2137
2169
  UIRenderer1.prototype._onClone.call(this, target);
@@ -2741,7 +2773,9 @@ __decorate([
2741
2773
  {
2742
2774
  key: "fontSize",
2743
2775
  get: /**
2744
- * The font size of the Text.
2776
+ * Font size in pixels, used for glyph rasterization.
2777
+ * Glyph pixel dimensions are converted to local UI units using the root canvas's
2778
+ * {@link UICanvas.referenceResolutionPerUnit}.
2745
2779
  */ function get() {
2746
2780
  return this._fontSize;
2747
2781
  },
@@ -2930,6 +2964,7 @@ var TextChunk = function TextChunk() {
2930
2964
  this._target = null;
2931
2965
  };
2932
2966
  /**
2967
+ * @internal
2933
2968
  * @inheritdoc
2934
2969
  */ _proto._onClone = function _onClone(target) {
2935
2970
  target._addStateValuesReferCount(1);
@@ -3268,13 +3303,12 @@ var UIPointerEventEmitter = /*#__PURE__*/ function(PointerEventEmitter1) {
3268
3303
  var scene = scenes[i];
3269
3304
  if (!scene.isActive || scene.destroyed) continue;
3270
3305
  var componentsManager = scene._componentsManager;
3271
- // Overlay Canvas
3272
3306
  var canvasElements = componentsManager._overlayCanvases;
3273
- // Screen to world ( Assume that world units have a one-to-one relationship with pixel units )
3307
+ // Convert screen coordinates to overlay coordinates.
3274
3308
  ray.origin.set(position.x, scene.engine.canvas.height - position.y, 1);
3275
3309
  ray.direction.set(0, 0, -1);
3276
3310
  for(var j = canvasElements.length - 1; j >= 0; j--){
3277
- if (canvasElements.get(j)._raycast(ray, hitResult)) {
3311
+ if (canvasElements.get(j)._raycast(ray, hitResult, Number.MAX_SAFE_INTEGER, Layer.Everything)) {
3278
3312
  this._updateRaycast(hitResult.component, pointer);
3279
3313
  return;
3280
3314
  }
@@ -3288,26 +3322,22 @@ var UIPointerEventEmitter = /*#__PURE__*/ function(PointerEventEmitter1) {
3288
3322
  continue;
3289
3323
  }
3290
3324
  camera.screenPointToRay(pointer.position, ray);
3291
- // Other canvases
3292
- var isOrthographic = camera.isOrthographic;
3293
- var _camera_entity_transform = camera.entity.transform, cameraPosition = _camera_entity_transform.worldPosition, cameraForward = _camera_entity_transform.worldForward;
3294
- // Sort by rendering order
3295
3325
  canvasElements = componentsManager._canvases;
3326
+ var isOrthographic = camera.isOrthographic, farClipPlane = camera.farClipPlane, cullingMask = camera.cullingMask;
3327
+ var _camera_entity_transform = camera.entity.transform, worldPosition = _camera_entity_transform.worldPosition, worldForward = _camera_entity_transform.worldForward;
3296
3328
  for(var k = 0, n = canvasElements.length; k < n; k++){
3297
- canvasElements.get(k)._updateSortDistance(isOrthographic, cameraPosition, cameraForward);
3329
+ canvasElements.get(k)._updateSortDistance(isOrthographic, worldPosition, worldForward);
3298
3330
  }
3299
- canvasElements.sort(function(a, b) {
3300
- return a.sortOrder - b.sortOrder || a._sortDistance - b._sortDistance;
3301
- });
3331
+ canvasElements.sort(UIPointerEventEmitter._compareRaycastOrder);
3332
+ // Update registry indices after sorting.
3302
3333
  for(var k1 = 0, n1 = canvasElements.length; k1 < n1; k1++){
3303
3334
  canvasElements.get(k1)._canvasIndex = k1;
3304
3335
  }
3305
- var farClipPlane = camera.farClipPlane;
3306
- // Post-rendering first detection
3336
+ // Fully tied canvases may differ in hit and draw order.
3307
3337
  for(var k2 = 0, n2 = canvasElements.length; k2 < n2; k2++){
3308
3338
  var canvas = canvasElements.get(k2);
3309
3339
  if (!canvas._canDispatchEvent(camera)) continue;
3310
- if (canvas._raycast(ray, hitResult, farClipPlane)) {
3340
+ if (canvas._raycast(ray, hitResult, farClipPlane, cullingMask)) {
3311
3341
  this._updateRaycast(hitResult.component, pointer);
3312
3342
  return;
3313
3343
  }
@@ -3468,6 +3498,9 @@ var UIPointerEventEmitter = /*#__PURE__*/ function(PointerEventEmitter1) {
3468
3498
  fireEvent(path[i], eventData);
3469
3499
  }
3470
3500
  };
3501
+ UIPointerEventEmitter._compareRaycastOrder = function _compareRaycastOrder(a, b) {
3502
+ return b.sortOrder - a.sortOrder || a._sortDistance - b._sortDistance;
3503
+ };
3471
3504
  return UIPointerEventEmitter;
3472
3505
  }(PointerEventEmitter);
3473
3506
  UIPointerEventEmitter._MAX_PATH_DEPTH = 2048;
@@ -3479,7 +3512,9 @@ UIPointerEventEmitter = __decorate([
3479
3512
  registerPointerEventEmitter()
3480
3513
  ], UIPointerEventEmitter);
3481
3514
 
3482
- var EngineExtension = /*#__PURE__*/ function() {
3515
+ /**
3516
+ * @internal
3517
+ */ var EngineExtension = /*#__PURE__*/ function() {
3483
3518
  function EngineExtension() {}
3484
3519
  var _proto = EngineExtension.prototype;
3485
3520
  _proto._getUIDefaultMaterial = function _getUIDefaultMaterial() {
@@ -3494,7 +3529,9 @@ var EngineExtension = /*#__PURE__*/ function() {
3494
3529
  };
3495
3530
  return EngineExtension;
3496
3531
  }();
3497
- var EntityExtension = /*#__PURE__*/ function() {
3532
+ /**
3533
+ * @internal
3534
+ */ var EntityExtension = /*#__PURE__*/ function() {
3498
3535
  function EntityExtension() {
3499
3536
  this._uiHierarchyVersion = 0;
3500
3537
  }