@sapui5/sap.ui.vk 1.139.0 → 1.141.0

package/src/sap/ui/vk/svg/Viewport.js

@@ -76,23 +76,13 @@ sap.ui.define([
 	 *
 	 * @public
 	 * @author SAP SE
-	 * @version 1.139.0
+	 * @version 1.141.0
 	 * @extends sap.ui.vk.ViewportBase
 	 * @alias sap.ui.vk.svg.Viewport
 	 */
 	var Viewport = ViewportBase.extend("sap.ui.vk.svg.Viewport", /** @lends sap.ui.vk.svg.Viewport.prototype  */ {
 		metadata: {
 			library: "sap.ui.vk",
-			// properties: {
-			// 	zoomInLimit: {
-			// 		type: "float",
-			// 		defaultValue: 500
-			// 	},
-			// 	zoomOutLimit: {
-			// 		type: "float",
-			// 		defaultValue: 0.25
-			// 	}
-			// },
 			aggregations: {
 				miniMap: {
 					type: "sap.m.Dialog",
@@ -245,9 +235,11 @@ sap.ui.define([
 		miniMapDialog.attachBeforeOpen(function() { miniMapDialog.oPopup.setModal(false); }); // dialog should not be modal
 		miniMapDialog._calcPosition = () => {
 			const rect = this.getDomRef()?.getBoundingClientRect() ?? { top: 0, right: 0 }; // viewport's bounding rect
+			const miniMapRect = miniMapDialog.getDomRef()?.getBoundingClientRect() ?? { width: 0, height: 0 }; // mini map dialog's bounding rect
+			const lockPos = miniMap._lockPosition;
 			return {
-				top: rect.top + 16 + "px",
-				left: rect.right - miniMap._width - 16 - 4 + "px"
+				top: (lockPos.y >= 0 ? rect.top + lockPos.y : Math.max(rect.bottom + lockPos.y - miniMapRect.height, rect.top)) + "px",
+				left: (lockPos.x >= 0 ? rect.left + lockPos.x : Math.max(rect.right + lockPos.x - miniMapRect.width, rect.left)) + "px"
 			};
 		};
 		miniMap.attachSizeChanged((event) => {
@@ -309,6 +301,97 @@ sap.ui.define([
 		}
 	};
 
+	Viewport.prototype._updateCustomText = function() {
+		const root = this._scene.getRootElement();
+
+		// collect all font sizes in the scene
+		const fontSizes = [];
+		root.traverse(function(node) {
+			if (node.type === "Text") {
+				const fontSizeCSS = node.style.size;
+				const fontSize = parseFloat(fontSizeCSS);
+				if (fontSize > 0) {
+					let unitScale = 1;
+					if (typeof fontSizeCSS === "string") {
+						if (fontSizeCSS.endsWith("em")) {
+							unitScale = 16; // assuming 1em = 16px
+						} else if (fontSizeCSS.endsWith("pt")) {
+							unitScale = 1.333; // assuming 1pt = 1.333px
+						}
+					}
+
+					const m = node._matrixWorld();
+					fontSizes.push(fontSize * unitScale * Math.sqrt(m[2] * m[2] + m[3] * m[3]));
+				}
+			}
+		});
+
+		let fontSize;
+		if (fontSizes.length > 0) {// take median font size
+			fontSizes.sort();
+			fontSize = fontSizes[fontSizes.length >> 1];
+		} else {
+			const bbox = root.domRef.getBBox();
+			fontSize = Math.max(bbox.width, bbox.height) * 0.01;
+		}
+		fontSize = Math.round(fontSize * 100) / 100; // round to 2 decimal places
+
+		root.traverse(function(node) {
+			if (node.customText?.style.size === "0px") { // "0px" is a special case, it means "default font size"
+				node.customText.style.size = fontSize + "px";
+			}
+		});
+	};
+
+	Viewport.prototype._updateCustomTextFilters = function() {
+		const domRef = this._scene?.getRootElement()?.domRef;
+		if (domRef) {
+			const blurStdDeviation = this.getHotspotCustomTextHaloWidth();
+			const dilateRadius = blurStdDeviation * 0.1; // 10% of blur std deviation
+			const outlineWidth = this.getHotspotCustomTextOutlineWidth();
+			const expand = Math.max(blurStdDeviation + dilateRadius, outlineWidth * 2);
+			const color = cssColorToColor(this.getHotspotCustomTextOutlineColor());
+			for (const filter of domRef.parentNode.getElementsByTagName("filter")) {
+				if (filter.id.endsWith("-custom-text")) {
+					if (sap.ui.Device.browser.firefox) {
+						filter.setAttribute("x", "-25%");
+						filter.setAttribute("y", "-100%");
+						filter.setAttribute("width", "150%");
+						filter.setAttribute("height", "300%");
+					} else {
+						filter.setAttribute("x", -expand + "px");
+						filter.setAttribute("y", -expand + "px");
+						filter.setAttribute("width", `calc(100% + ${expand * 2}px)`);
+						filter.setAttribute("height", `calc(100% + ${expand * 2}px)`);
+					}
+					filter.childNodes[0].setAttribute("radius", dilateRadius); // set morphology dilate radius
+					filter.childNodes[2].setAttribute("stdDeviation", blurStdDeviation); // set gaussian blur std deviation
+					filter.childNodes[3].setAttribute("radius", outlineWidth); // set morphology dilate radius
+					filter.childNodes[5].setAttribute("stdDeviation", outlineWidth); // set gaussian blur std deviation
+					filter.childNodes[4].setAttribute("values", `0 0 0 0 ${color.red / 255}, 0 0 0 0 ${color.green / 255}, 0 0 0 0 ${color.blue / 255}, 0 0 0 ${color.alpha} 0`);
+				}
+			}
+		}
+	};
+
+	Viewport.prototype.setHotspotCustomTextOutlineColor = function(cssColor) {
+		this.setProperty("hotspotCustomTextOutlineColor", cssColor, true);
+		this._updateCustomTextFilters();
+		return this;
+	};
+
+	Viewport.prototype.setHotspotCustomTextOutlineWidth = function(width) {
+		this.setProperty("hotspotCustomTextOutlineWidth", width, true);
+		this._updateCustomTextFilters();
+		return this;
+	};
+
+	Viewport.prototype.setHotspotCustomTextHaloWidth = function(width) {
+		this.setProperty("hotspotCustomTextHaloWidth", width, true);
+		this._updateCustomTextFilters();
+		return this;
+	};
+
 	Viewport.prototype.onAfterRendering = function() {
 		this._resizeListenerId = ResizeHandler.register(this, this._handleResize.bind(this));
 
@@ -319,6 +402,8 @@ sap.ui.define([
 			var root = this._scene.getRootElement();
 			root._setDomRef(document.getElementById(root.uid));
 			this._svgElement = root.domRef.parentNode;
+
+			this._updateCustomText();
 		}
 
 		this._handleResize({
@@ -523,28 +608,47 @@ sap.ui.define([
 
 		var rootElement = this._scene.getRootElement();
 		var viewportRect = this.getDomRef().getBoundingClientRect();
+		x += viewportRect.x;
+		y += viewportRect.y;
 
-		var hitTest = function(x, y) {
-			var htmlElement;
-			if (ignoreHotspots) {
-				var htmlElements = document.elementsFromPoint(x + viewportRect.x, y + viewportRect.y);
-				for (var i = 0; i < htmlElements.length; i++) {
-					htmlElement = htmlElements[i];
-					var hit = htmlElement != null && htmlElement.id ? rootElement.getElementById(htmlElement.id) : null;
-					if (!hit) {
-						return null;
-					}
-					var elem = hit._getSceneTreeElement();
-					if (elem && elem._vkGetNodeContentType() !== NodeContentType.Hotspot) {
-						return hit;
-					}
+		function getHit(htmlElement) {
+			while (htmlElement && !htmlElement.id) {
+				htmlElement = htmlElement.parentElement; // go up the DOM tree to find an element with id
+			}
+			if (!htmlElement) {
+				return null; // element not found
+			}
+
+			const hit = rootElement.getElementById(htmlElement.id);
+			const elem = hit?._getSceneTreeElement();
+			if (!elem) {
+				return null; // element not found in the scene
+			}
+
+			if ((ignoreHotspots && elem._vkGetNodeContentType() === NodeContentType.Hotspot) ||
+				hit.userData.customText) {
+				return undefined; // ignore hotspots if the "ignoreHotspots" flag is set and ignore custom text elements
+			}
+
+			return hit;
+		}
+
+		function hitTest(x, y) {
+			const htmlElement = document.elementFromPoint(x, y);
+			const hit = getHit(htmlElement);
+			if (hit !== undefined) {
+				return hit;
+			}
+
+			for (const htmlElement of document.elementsFromPoint(x, y)) {
+				const hit = getHit(htmlElement);
+				if (hit !== undefined) {
+					return hit;
 				}
-				return null;
-			} else {
-				htmlElement = document.elementFromPoint(x + viewportRect.x, y + viewportRect.y);
-				return htmlElement !== null && htmlElement.id ? rootElement.getElementById(htmlElement.id) : null;
 			}
-		};
+
+			return null; // no hit found
+		}
 
 		var hit = hitTest(x, y);
 		if (withTolerance) {
@@ -1288,6 +1392,15 @@ sap.ui.define([
 			activeHotspotChanged = true;
 		}
 
+		if (this._dynamicContentElement && this._dynamicContentElement !== elem) {
+			this.fireHotspotLeave({ nodeRef: this._dynamicContentElement });
+			if (!this.getShowAllDynamicContents()) {
+				this._dynamicContentElement.setHotspotColor(vsm._mask, null);
+			}
+			this._dynamicContentElement = null;
+			activeHotspotChanged = true;
+		}
+
 		if (elem && elem._vkGetNodeContentType() === NodeContentType.Hotspot) {
 			this._hotspotElement = elem;
 			if (!this.getShowAllHotspots()) {
@@ -1297,6 +1410,15 @@ sap.ui.define([
 			activeHotspotChanged = true;
 		}
 
+		if (elem && elem._vkGetNodeContentType() === NodeContentType.DynamicContent) {
+			this._dynamicContentElement = elem;
+			if (!this.getShowAllDynamicContents()) {
+				elem.setHotspotColor(vsm._mask, this.getHotspotColorABGR());
+			}
+			this.fireHotspotEnter({ nodeRef: elem });
+			activeHotspotChanged = true;
+		}
+
 		if (activeHotspotChanged) {
 			this._invalidateRasterImage();
 		}
@@ -1645,6 +1767,30 @@ sap.ui.define([
 		return this;
 	};
 
+	Viewport.prototype.setShowAllDynamicContents = function(value) {
+		this.setProperty("showAllDynamicContents", value, true);
+		const vsm = this._getViewStateManagerSVG();
+		if (vsm) {
+			const vsmMask = vsm._mask;
+			const nodes = vsm.getNodeHierarchy().getDynamicContentNodeRefs();
+			const dynamicContentElement = this._dynamicContentElement;
+			const color = this.getShowAllHotspotsTintColor();
+			nodes.forEach(function(node) {
+				if (value) {
+					node.setHotspotColor(vsmMask, color);
+				} else if (node === dynamicContentElement) {
+					node.setHotspotColor(vsmMask, this.getHotspotColorABGR());
+				} else {
+					node.setHotspotColor(vsmMask, null);
+				}
+			}, this);
+
+			if (nodes.length > 0) {
+				this.invalidate();
+			}
+		}
+	};
+
 	Viewport.prototype._getFillStyleId = function(element) {
 		if (element.highlightColor || element.tintColor) {
 			return null;

package/src/sap/ui/vk/svg/ViewportRenderer.js

@@ -56,6 +56,12 @@ sap.ui.define([
 			var highlightColor = abgrToColor(vsm._highlightColorABGR);
 			var hotspotColor = abgrToColor(viewport.getHotspotColorABGR());
 			var tintColor = cssColorToColor(viewport.getShowAllHotspotsTintColor());
+			const customTextBlurStdDeviation = viewport.getHotspotCustomTextHaloWidth();
+			const customTextDilateRadius = customTextBlurStdDeviation * 0.1; // 10% of blur std deviation
+			const customTextOutlineColor = cssColorToColor(viewport.getHotspotCustomTextOutlineColor());
+			const customTextOutlineRadius = viewport.getHotspotCustomTextOutlineWidth();
+			const customTextFilterExpand = Math.max(customTextBlurStdDeviation + customTextDilateRadius, customTextOutlineRadius * 2);
+
 			hotspotEffects.set(Element._hotspotEffectName(highlightColor), highlightColor);
 			hotspotEffects.set(Element._hotspotEffectName(hotspotColor), hotspotColor);
 			hotspotEffects.set(Element._hotspotEffectName(tintColor), tintColor);
@@ -78,6 +84,82 @@ sap.ui.define([
 				rm.openEnd();
 				rm.close("feColorMatrix");
 				rm.close("filter");
+
+				rm.openStart("filter");
+				rm.attr("id", name + "-custom-text");
+				if (sap.ui.Device.browser.firefox) {
+					rm.attr("x", "-25%");
+					rm.attr("y", "-100%");
+					rm.attr("width", "150%");
+					rm.attr("height", "300%");
+				} else {
+					rm.attr("x", -customTextFilterExpand + "px");
+					rm.attr("y", -customTextFilterExpand + "px");
+					rm.attr("width", `calc(100% + ${customTextFilterExpand * 2}px)`);
+					rm.attr("height", `calc(100% + ${customTextFilterExpand * 2}px)`);
+				}
+				rm.openEnd();
+
+				rm.openStart("feMorphology");
+				rm.attr("in", "SourceAlpha");
+				rm.attr("result", "blurOut");
+				rm.attr("operator", "dilate");
+				rm.attr("radius", customTextDilateRadius);
+				rm.openEnd();
+				rm.close("feMorphology");
+
+				rm.openStart("feColorMatrix");
+				rm.attr("in", "blurOut");
+				rm.attr("result", "blurOut");
+				rm.attr("type", "matrix");
+				rm.attr("values", "0 0 0 0 " + (color.red / 255) + ", 0 0 0 0 " + (color.green / 255) + ", 0 0 0 0 " + (color.blue / 255) + ", 0 0 0 1 0");
+				rm.openEnd();
+				rm.close("feColorMatrix");
+
+				rm.openStart("feGaussianBlur");
+				rm.attr("in", "blurOut");
+				rm.attr("result", "blurOut");
+				rm.attr("stdDeviation", customTextBlurStdDeviation);
+				rm.openEnd();
+				rm.close("feGaussianBlur");
+
+				rm.openStart("feMorphology");
+				rm.attr("in", "SourceAlpha");
+				rm.attr("result", "outline");
+				rm.attr("operator", "dilate");
+				rm.attr("radius", customTextOutlineRadius);
+				rm.openEnd();
+				rm.close("feMorphology");
+
+				rm.openStart("feColorMatrix");
+				rm.attr("in", "outline");
+				rm.attr("result", "outline");
+				rm.attr("type", "matrix");
+				rm.attr("values", "0 0 0 0 " + (customTextOutlineColor.red / 255) + ", 0 0 0 0 " + (customTextOutlineColor.green / 255) + ", 0 0 0 0 " + (customTextOutlineColor.blue / 255) + ", 0 0 0 " + customTextOutlineColor.alpha + " 0");
+				rm.openEnd();
+				rm.close("feColorMatrix");
+
+				rm.openStart("feGaussianBlur");
+				rm.attr("in", "outline");
+				rm.attr("result", "outline");
+				rm.attr("stdDeviation", customTextOutlineRadius);
+				rm.openEnd();
+				rm.close("feGaussianBlur");
+
+				rm.openStart("feBlend");
+				rm.attr("in", "blurOut");
+				rm.attr("in2", "outline");
+				rm.attr("result", "blurOut");
+				rm.openEnd();
+				rm.close("feBlend");
+
+				rm.openStart("feBlend");
+				rm.attr("in", "SourceGraphic");
+				rm.attr("in2", "blurOut");
+				rm.openEnd();
+				rm.close("feBlend");
+
+				rm.close("filter");
 			});
 
 			scene.getRootElement().render(rm, vsm ? vsm._mask : (-1 | 0), viewport);

package/src/sap/ui/vk/thirdparty/BufferGeometryUtils.js

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright 2010-2023 Three.js Authors
+ * Copyright 2010-2025 Three.js Authors
  * SPDX-License-Identifier: MIT
  */
 
@@ -14,6 +14,30 @@ sap.ui.define([
 var Module = (function (exports, three) {
 	'use strict';
 
+	/**
+	 * @module BufferGeometryUtils
+	 * @three_import import * as BufferGeometryUtils from 'three/addons/utils/BufferGeometryUtils.js';
+	 */
+
+	/**
+	 * Computes vertex tangents using the MikkTSpace algorithm. MikkTSpace generates the same tangents consistently,
+	 * and is used in most modelling tools and normal map bakers. Use MikkTSpace for materials with normal maps,
+	 * because inconsistent tangents may lead to subtle visual issues in the normal map, particularly around mirrored
+	 * UV seams.
+	 *
+	 * In comparison to this method, {@link BufferGeometry#computeTangents} (a custom algorithm) generates tangents that
+	 * probably will not match the tangents in other software. The custom algorithm is sufficient for general use with a
+	 * custom material, and may be faster than MikkTSpace.
+	 *
+	 * Returns the original BufferGeometry. Indexed geometries will be de-indexed. Requires position, normal, and uv attributes.
+	 *
+	 * @param {BufferGeometry} geometry - The geometry to compute tangents for.
+	 * @param {Object} MikkTSpace - Instance of `examples/jsm/libs/mikktspace.module.js`, or `mikktspace` npm package.
+	 * Await `MikkTSpace.ready` before use.
+	 * @param {boolean} [negateSign=true] - Whether to negate the sign component (.w) of each tangent.
+	 * Required for normal map conventions in some formats, including glTF.
+	 * @return {BufferGeometry} The updated geometry.
+	 */
 	function computeMikkTSpaceTangents( geometry, MikkTSpace, negateSign = true ) {
 
 		if ( ! MikkTSpace || ! MikkTSpace.isReady ) {
@@ -103,9 +127,11 @@ var Module = (function (exports, three) {
 	}
 
 	/**
-	 * @param  {Array<BufferGeometry>} geometries
-	 * @param  {Boolean} useGroups
-	 * @return {BufferGeometry}
+	 * Merges a set of geometries into a single instance. All geometries must have compatible attributes.
+	 *
+	 * @param {Array<BufferGeometry>} geometries - The geometries to merge.
+	 * @param {boolean} [useGroups=false] - Whether to use groups or not.
+	 * @return {?BufferGeometry} The merged geometry. Returns `null` if the merge does not succeed.
 	 */
 	function mergeGeometries( geometries, useGroups = false ) {
 
@@ -299,8 +325,11 @@ var Module = (function (exports, three) {
 	}
 
 	/**
-	 * @param {Array<BufferAttribute>} attributes
-	 * @return {BufferAttribute}
+	 * Merges a set of attributes into a single instance. All attributes must have compatible properties and types.
+	 * Instances of {@link InterleavedBufferAttribute} are not supported.
+	 *
+	 * @param {Array<BufferAttribute>} attributes - The attributes to merge.
+	 * @return {?BufferAttribute} The merged attribute. Returns `null` if the merge does not succeed.
 	 */
 	function mergeAttributes( attributes ) {
 
@@ -392,8 +421,10 @@ var Module = (function (exports, three) {
 	}
 
 	/**
-	 * @param {BufferAttribute}
-	 * @return {BufferAttribute}
+	 * Performs a deep clone of the given buffer attribute.
+	 *
+	 * @param {BufferAttribute} attribute - The attribute to clone.
+	 * @return {BufferAttribute} The cloned attribute.
 	 */
 	function deepCloneAttribute( attribute ) {
 
@@ -414,8 +445,11 @@ var Module = (function (exports, three) {
 	}
 
 	/**
-	 * @param {Array<BufferAttribute>} attributes
-	 * @return {Array<InterleavedBufferAttribute>}
+	 * Interleaves a set of attributes and returns a new array of corresponding attributes that share a
+	 * single {@link InterleavedBuffer} instance. All attributes must have compatible types.
+	 *
+	 * @param {Array<BufferAttribute>} attributes - The attributes to interleave.
+	 * @return {Array<InterleavedBufferAttribute>} An array of interleaved attributes. If interleave does not succeed, the method returns `null`.
 	 */
 	function interleaveAttributes( attributes ) {
 
@@ -478,7 +512,12 @@ var Module = (function (exports, three) {
 
 	}
 
-	// returns a new, non-interleaved version of the provided attribute
+	/**
+	 * Returns a new, non-interleaved version of the given attribute.
+	 *
+	 * @param {InterleavedBufferAttribute} attribute - The interleaved attribute.
+	 * @return {BufferAttribute} The non-interleaved attribute.
+	 */
 	function deinterleaveAttribute( attribute ) {
 
 		const cons = attribute.data.array.constructor;
@@ -526,7 +565,11 @@ var Module = (function (exports, three) {
 
 	}
 
-	// deinterleaves all attributes on the geometry
+	/**
+	 * Deinterleaves all attributes on the given geometry.
+	 *
+	 * @param {BufferGeometry} geometry - The geometry to deinterleave.
+	 */
 	function deinterleaveGeometry( geometry ) {
 
 		const attributes = geometry.attributes;
@@ -570,8 +613,10 @@ var Module = (function (exports, three) {
 	}
 
 	/**
-	 * @param {BufferGeometry} geometry
-	 * @return {number}
+	 * Returns the amount of bytes used by all attributes to represent the geometry.
+	 *
+	 * @param {BufferGeometry} geometry - The geometry.
+	 * @return {number} The estimate bytes used.
 	 */
 	function estimateBytesUsed( geometry ) {
 
@@ -593,9 +638,11 @@ var Module = (function (exports, three) {
 	}
 
 	/**
-	 * @param {BufferGeometry} geometry
-	 * @param {number} tolerance
-	 * @return {BufferGeometry}
+	 * Returns a new geometry with vertices for which all similar vertex attributes (within tolerance) are merged.
+	 *
+	 * @param {BufferGeometry} geometry - The geometry to merge vertices for.
+	 * @param {number} [tolerance=1e-4] - The tolerance value.
+	 * @return {BufferGeometry} - The new geometry with merged vertices.
 	 */
 	function mergeVertices( geometry, tolerance = 1e-4 ) {
 
@@ -756,9 +803,12 @@ var Module = (function (exports, three) {
 	}
 
 	/**
-	 * @param {BufferGeometry} geometry
-	 * @param {number} drawMode
-	 * @return {BufferGeometry}
+	 * Returns a new indexed geometry based on `TrianglesDrawMode` draw mode.
+	 * This mode corresponds to the `gl.TRIANGLES` primitive in WebGL.
+	 *
+	 * @param {BufferGeometry} geometry - The geometry to convert.
+	 * @param {number} drawMode - The current draw mode.
+	 * @return {BufferGeometry} The new geometry using `TrianglesDrawMode`.
 	 */
 	function toTrianglesDrawMode( geometry, drawMode ) {
 
@@ -867,9 +917,13 @@ var Module = (function (exports, three) {
 
 	/**
 	 * Calculates the morphed attributes of a morphed/skinned BufferGeometry.
-	 * Helpful for Raytracing or Decals.
-	 * @param {Mesh | Line | Points} object An instance of Mesh, Line or Points.
-	 * @return {Object} An Object with original position/normal attributes and morphed ones.
+	 *
+	 * Helpful for Raytracing or Decals (i.e. a `DecalGeometry` applied to a morphed Object with a `BufferGeometry`
+	 * will use the original `BufferGeometry`, not the morphed/skinned one, generating an incorrect result.
+	 * Using this function to create a shadow `Object3`D the `DecalGeometry` can be correctly generated).
+	 *
+	 * @param {Mesh|Line|Points} object - The 3D object to compute morph attributes for.
+	 * @return {Object} An object with original position/normal attributes and morphed ones.
 	 */
 	function computeMorphedAttributes( object ) {
 
@@ -1145,6 +1199,12 @@ var Module = (function (exports, three) {
 
 	}
 
+	/**
+	 * Merges the {@link BufferGeometry#groups} for the given geometry.
+	 *
+	 * @param {BufferGeometry} geometry - The geometry to modify.
+	 * @return {BufferGeometry} - The updated geometry
+	 */
 	function mergeGroups( geometry ) {
 
 		if ( geometry.groups.length === 0 ) {
@@ -1247,15 +1307,14 @@ var Module = (function (exports, three) {
 
 	}
 
-
 	/**
 	 * Modifies the supplied geometry if it is non-indexed, otherwise creates a new,
 	 * non-indexed geometry. Returns the geometry with smooth normals everywhere except
 	 * faces that meet at an angle greater than the crease angle.
 	 *
-	 * @param {BufferGeometry} geometry
-	 * @param {number} [creaseAngle]
-	 * @return {BufferGeometry}
+	 * @param {BufferGeometry} geometry - The geometry to modify.
+	 * @param {number} [creaseAngle=Math.PI/3] - The crease angle in radians.
+	 * @return {BufferGeometry} - The updated geometry
 	 */
 	function toCreasedNormals( geometry, creaseAngle = Math.PI / 3 /* 60 degrees */ ) {