Integration of outline and shadow to label

cocos/2d/assembler/label/letter-font.ts

@@ -25,7 +25,7 @@
 import { js } from '../../../core';
 import { Label, LabelOutline } from '../../components';
 import { bmfontUtils } from './bmfontUtils';
-import { shareLabelInfo, LetterAtlas, computeHash } from './font-utils';
+import { shareLabelInfo, LetterAtlas, computeHash, LetterRenderTexture } from './font-utils';
 
 const _atlasWidth = 1024;
 const _atlasHeight = 1024;
@@ -39,20 +39,20 @@ export const letterFont = js.mixin(bmfontUtils, {
             _shareAtlas = new LetterAtlas(_atlasWidth, _atlasHeight);
         }
 
-        return _shareAtlas.getTexture();
+        return _shareAtlas.getTexture() as LetterRenderTexture | null;
     },
 
     _updateFontFamily (comp) {
         shareLabelInfo.fontAtlas = _shareAtlas;
         shareLabelInfo.fontFamily = this._getFontFamily(comp);
 
         // outline
-        const outline = comp.getComponent(LabelOutline);
-        if (outline && outline.enabled) {
+        const isOutlined = comp.outlineUsed && comp.outlineWidth > 0;
+        if (isOutlined) {
             shareLabelInfo.isOutlined = true;
-            shareLabelInfo.margin = outline.width;
-            shareLabelInfo.out = outline.color.clone();
-            shareLabelInfo.out.a = outline.color.a * comp.color.a / 255.0;
+            shareLabelInfo.margin = comp.outlineWidth;
+            shareLabelInfo.out = comp.outlineColor.clone();
+            shareLabelInfo.out.a = comp.outlineColor.color.a * comp.color.a / 255.0;
         } else {
             shareLabelInfo.isOutlined = false;
             shareLabelInfo.margin = 0;

cocos/2d/assembler/label/ttfUtils.ts

@@ -21,7 +21,7 @@
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  THE SOFTWARE.
 */
-import { Label, LabelOutline, LabelShadow } from '../../components';
+import { Label } from '../../components';
 import { ISharedLabelData } from './font-utils';
 import { UITransform } from '../../framework/ui-transform';
 import { dynamicAtlasManager } from '../../utils/dynamic-atlas/atlas-manager';
@@ -35,8 +35,14 @@ const Overflow = Label.Overflow;
 
 export const ttfUtils =  {
 
-    updateProcessingData (style: TextStyle, layout: TextLayout,
-        outputLayoutData: TextOutputLayoutData, outputRenderData: TextOutputRenderData, comp: Label, trans: UITransform): void {
+    updateProcessingData (
+        style: TextStyle,
+        layout: TextLayout,
+        outputLayoutData: TextOutputLayoutData,
+        outputRenderData: TextOutputRenderData,
+        comp: Label,
+        trans: UITransform,
+    ): void {
         // font info // both
         style.isSystemFontUsed = comp.useSystemFont;
         style.fontSize = comp.fontSize;
@@ -62,25 +68,23 @@ export const ttfUtils =  {
         style.underlineHeight = comp.underlineHeight;
 
         // outline// both
-        let outlineComp = LabelOutline && comp.getComponent(LabelOutline);
-        outlineComp = (outlineComp && outlineComp.enabled && outlineComp.width > 0) ? outlineComp : null;
-        if (outlineComp) {
+        const isOutlined = comp.outlineUsed && comp.outlineWidth > 0;
+        if (isOutlined) {
             style.isOutlined = true;
-            style.outlineColor.set(outlineComp.color);
-            style.outlineWidth = outlineComp.width;
+            style.outlineColor.set(comp.outlineColor);
+            style.outlineWidth = comp.outlineWidth;
         } else {
             style.isOutlined = false;
         }
 
         // shadow// both
-        let shadowComp = LabelShadow && comp.getComponent(LabelShadow);
-        shadowComp = (shadowComp && shadowComp.enabled) ? shadowComp : null;
-        if (shadowComp) {
+        const isShadow = comp.shadowUsed;
+        if (isShadow) {
             style.hasShadow = true;
-            style.shadowColor.set(shadowComp.color);
-            style.shadowBlur = shadowComp.blur;
-            style.shadowOffsetX = shadowComp.offset.x;
-            style.shadowOffsetY = shadowComp.offset.y;
+            style.shadowColor.set(comp.shadowColor);
+            style.shadowBlur = comp.shadowBlur;
+            style.shadowOffsetX = comp.shadowOffset.x;
+            style.shadowOffsetY = comp.shadowOffset.y;
         } else {
             style.hasShadow = false;
         }
@@ -126,8 +130,15 @@ export const ttfUtils =  {
 
             // TextProcessing
             processing.processingString(false, style, layout, outputLayoutData, comp.string);
-            processing.generateRenderInfo(false, style, layout, outputLayoutData, outputRenderData,
-                comp.string, this.generateVertexData);
+            processing.generateRenderInfo(
+                false,
+                style,
+                layout,
+                outputLayoutData,
+                outputRenderData,
+                comp.string,
+                this.generateVertexData,
+            );
 
             const renderData = comp.renderData;
             renderData.textureDirty = true;
@@ -173,9 +184,11 @@ export const ttfUtils =  {
     },
 
     updateVertexData (comp: Label): void {
+        // no needs to update vertex data
     },
 
     updateUVs (comp: Label): void {
+        // no needs to update uv data
     },
 
     _updateFontFamily (comp: Label): string {

cocos/2d/components/deprecated.ts

@@ -31,7 +31,8 @@ import { UIMeshRenderer } from './ui-mesh-renderer';
 import { Graphics } from './graphics';
 import { UIStaticBatch } from './ui-static-batch';
 import { UIOpacity } from './ui-opacity';
-import { js, cclegacy, replaceProperty } from '../../core';
+import { js, cclegacy, replaceProperty, markAsWarning } from '../../core';
+import { LabelShadow } from './label-shadow';
 
 /**
  * Alias of [[Mask]]
@@ -125,3 +126,29 @@ replaceProperty(MaskType, 'MaskType', [
         targetName: 'MaskType',
     },
 ]);
+
+markAsWarning(LabelOutline.prototype, 'LabelOutline.prototype', [
+    {
+        name: 'width',
+        suggest: 'Please use Label.prototype.outlineWidth instead.',
+    },
+    {
+        name: 'color',
+        suggest: 'Please use Label.prototype.outlineColor instead.',
+    },
+]);
+
+markAsWarning(LabelShadow.prototype, 'LabelShadow.prototype', [
+    {
+        name: 'color',
+        suggest: 'Please use Label.prototype.shadowColor instead.',
+    },
+    {
+        name: 'offset',
+        suggest: 'Please use Label.prototype.shadowOffset instead.',
+    },
+    {
+        name: 'blur',
+        suggest: 'Please use Label.prototype.shadowBlur instead.',
+    },
+]);

cocos/2d/components/label-outline.ts

@@ -35,15 +35,7 @@ import { Label } from './label';
  * @zh
  * 描边效果组件,用于字体描边,只能用于系统字体。
  *
- * @example
- * ```ts
- * import { Node, Label, LabelOutline } from 'cc';
- * // Create a new node and add label components.
- * const node = new Node("New Label");
- * const label = node.addComponent(Label);
- * const outline = node.addComponent(LabelOutline);
- * node.parent = this.node;
- * ```
+ * @deprecated since v3.8.2, please use [[Label.outlineUsed]] instead.
  */
 @ccclass('cc.LabelOutline')
 @help('i18n:cc.LabelOutline')
@@ -64,11 +56,7 @@ export class LabelOutline extends Component {
      * @zh
      * 改变描边的颜色。
      *
-     * @example
-     * ```ts
-     * import { Color } from 'cc';
-     * outline.color = new Color(0.5, 0.3, 0.7, 1.0);
-     * ```
+     * @deprecated since v3.8.2, please use [[Label.outlineColor]] instead.
      */
     @tooltip('i18n:labelOutline.color')
     // @constget
@@ -82,7 +70,10 @@ export class LabelOutline extends Component {
         }
 
         this._color.set(value);
-        this._updateRenderData();
+        const label = this.node.getComponent(Label);
+        if (label) {
+            label.outlineColor = this._color;
+        }
     }
 
     /**
@@ -92,10 +83,7 @@ export class LabelOutline extends Component {
      * @zh
      * 改变描边的宽度。
      *
-     * @example
-     * ```ts
-     * outline.width = 3;
-     * ```
+     * @deprecated since v3.8.2, please use [[Label.outlineWidth]] instead.
      */
     @tooltip('i18n:labelOutline.width')
     get width (): number {
@@ -108,21 +96,39 @@ export class LabelOutline extends Component {
         }
 
         this._width = value;
-        this._updateRenderData();
+        const label = this.node.getComponent(Label);
+        if (label) {
+            label.outlineWidth = this._width;
+        }
     }
 
+    /**
+     * @deprecated since v3.8.2, please use [[Label.outlineUsed]] instead.
+     */
     public onEnable (): void {
-        this._updateRenderData();
+        const label = this.node.getComponent(Label);
+        if (label) {
+            label.outlineUsed = true;
+        }
     }
 
+    /**
+     * @deprecated since v3.8.2, please use [[Label.outlineUsed]] instead.
+     */
     public onDisable (): void {
-        this._updateRenderData();
+        const label = this.node.getComponent(Label);
+        if (label) {
+            label.outlineUsed = false;
+        }
     }
 
-    protected _updateRenderData (): void {
+    /**
+     * @deprecated since v3.8.2, please use [[Label.outlineUsed]] instead.
+     */
+    public onLoad (): void {
         const label = this.node.getComponent(Label);
-        if (label) {
-            label.updateRenderData(true);
+        if (label && this.enabledInHierarchy) {
+            label.outlineUsed = true;
         }
     }
 }

cocos/2d/components/label-shadow.ts

@@ -31,13 +31,8 @@ import { Label } from './label';
 /**
  * @en Shadow effect for Label component, only for system fonts or TTF fonts.
  * @zh 用于给 Label 组件添加阴影效果，只能用于系统字体或 ttf 字体。
- * @example
- * import { Node, Label, LabelShadow } from 'cc';
- * // Create a new node and add label components.
- * const node = new Node("New Label");
- * const label = node.addComponent(Label);
- * const shadow = node.addComponent(LabelShadow);
- * node.parent = this.node;
+ *
+ * @deprecated since v3.8.2, please use [[Label.shadowUsed]] instead.
  */
 @ccclass('cc.LabelShadow')
 @help('i18n:cc.LabelShadow')
@@ -60,11 +55,7 @@ export class LabelShadow extends Component {
      * @zh
      * 阴影的颜色。
      *
-     * @example
-     * ```ts
-     * import { Color } from 'cc';
-     * labelShadow.color = new Color(0.5, 0.3, 0.7, 1.0);
-     * ```
+     * @deprecated since v3.8.2, please use [[Label.shadowColor]] instead.
      */
     @tooltip('i18n:labelShadow.color')
     get color (): Readonly<Color> {
@@ -77,7 +68,10 @@ export class LabelShadow extends Component {
         }
 
         this._color.set(value);
-        this._updateRenderData();
+        const label = this.node.getComponent(Label);
+        if (label) {
+            label.shadowColor = this._color;
+        }
     }
 
     /**
@@ -87,11 +81,7 @@ export class LabelShadow extends Component {
      * @zh
      * 字体与阴影的偏移。
      *
-     * @example
-     * ```ts
-     * import { Vec2 } from 'cc';
-     * labelShadow.offset = new Vec2(2, 2);
-     * ```
+     * @deprecated since v3.8.2, please use [[Label.shadowOffset]] instead.
      */
     @tooltip('i18n:labelShadow.offset')
     get offset (): Vec2 {
@@ -100,7 +90,10 @@ export class LabelShadow extends Component {
 
     set offset (value) {
         this._offset = value;
-        this._updateRenderData();
+        const label = this.node.getComponent(Label);
+        if (label) {
+            label.shadowOffset = this._offset;
+        }
     }
 
     /**
@@ -110,10 +103,7 @@ export class LabelShadow extends Component {
      * @zh
      * 阴影的模糊程度。
      *
-     * @example
-     * ```ts
-     * labelShadow.blur = 2;
-     * ```
+     * @deprecated since v3.8.2, please use [[Label.shadowBlur]] instead.
      */
     @tooltip('i18n:labelShadow.blur')
     get blur (): number {
@@ -122,21 +112,39 @@ export class LabelShadow extends Component {
 
     set blur (value) {
         this._blur = value;
-        this._updateRenderData();
+        const label = this.node.getComponent(Label);
+        if (label) {
+            label.shadowBlur = this._blur;
+        }
     }
 
+    /**
+     * @deprecated since v3.8.2, please use [[Label.shadowUsed]] instead.
+     */
     public onEnable (): void {
-        this._updateRenderData();
+        const label = this.node.getComponent(Label);
+        if (label) {
+            label.shadowUsed = true;
+        }
     }
 
+    /**
+     * @deprecated since v3.8.2, please use [[Label.shadowUsed]] instead.
+     */
     public onDisable (): void {
-        this._updateRenderData();
+        const label = this.node.getComponent(Label);
+        if (label) {
+            label.shadowUsed = false;
+        }
     }
 
-    protected _updateRenderData (): void {
+    /**
+     * @deprecated since v3.8.2, please use [[Label.outlineUsed]] instead.
+     */
+    public onLoad (): void {
         const label = this.node.getComponent(Label);
-        if (label) {
-            label.updateRenderData(true);
+        if (label && this.enabledInHierarchy) {
+            label.shadowUsed = true;
         }
     }
 }