feat(渲染能力): 完善三维渲染、字体及版本保存

ofdgo_u3d_animation.go

@@ -0,0 +1,176 @@
+// Copyright 2025-2026 肖其顿 (XIAO QI DUN)
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package ofdgo
+
+import (
+	"context"
+	"fmt"
+	"io"
+)
+
+// U3DAnimation 保存ECMA-363第9.7.3节的动画修饰器，Index为链内位置
+// Attributes的1、2、4、8分别表示启动、锁定根骨骼、单轨播放和动作间平滑过渡
+// TimeScale为整体时间倍率，BlendTime以毫秒计；Motions为空时使用无轨道的默认动作
+type U3DAnimation struct {
+	Index, Attributes    uint32
+	TimeScale, BlendTime float32
+	Motions              []U3DAnimationMotion
+}
+
+// U3DAnimationMotion 保存动画中的动作引用，空名称引用默认动作
+// Attributes的1、2分别表示循环和同步结束，TimeOffset以毫秒计，TimeScale为动作时间倍率
+type U3DAnimationMotion struct {
+	Name                  string
+	Attributes            uint32
+	TimeOffset, TimeScale float32
+}
+
+// animation 读取动画参数及有序动作引用，不在解码时调度或求值
+// 入参: r 字段读取器, name 所属链名, chain 链类型, index 链内位置
+// 返回: error 结构、参数、预算或取消错误
+func (d *u3dDecoder) animation(r *u3dValues, name string, chain int, index uint32) error {
+	animation := U3DAnimation{Index: index, Attributes: r.u32(), TimeScale: r.f32()}
+	count := r.u32()
+	if r.err != nil {
+		return r.err
+	}
+	if len(r.data)-r.pos < 4 || uint64(count) > uint64(len(r.data)-r.pos-4)/14 {
+		return io.ErrUnexpectedEOF
+	}
+	if err := d.reserve(uint64(count), 32); err != nil {
+		return err
+	}
+	if count != 0 {
+		animation.Motions = make([]U3DAnimationMotion, int(count))
+	}
+	for i := range animation.Motions {
+		if i%256 == 0 {
+			if err := d.ctx.Err(); err != nil {
+				return err
+			}
+		}
+		motion := &animation.Motions[i]
+		motion.Name, motion.Attributes = r.text(), r.u32()
+		motion.TimeOffset, motion.TimeScale = r.f32(), r.f32()
+		if r.err != nil {
+			return r.err
+		}
+	}
+	animation.BlendTime = r.f32()
+	if err := r.done(); err != nil {
+		return err
+	}
+	if err := animation.validate(d.ctx); err != nil {
+		return err
+	}
+	if chain == 1 {
+		mesh := &d.meshes[name].mesh
+		mesh.Animations = append(mesh.Animations, animation)
+	} else {
+		node := &d.model.Nodes[d.nodes[name]]
+		node.Animations = append(node.Animations, animation)
+	}
+	return nil
+}
+
+// validate 校验动画属性及有限数值，保留零倍率与反向播放倍率
+// 入参: ctx 取消上下文
+// 返回: error 参数或取消错误
+func (animation U3DAnimation) validate(ctx context.Context) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	if animation.Index == 0 || animation.Attributes & ^uint32(15) != 0 || !finite(float64(animation.TimeScale)) || !finite(float64(animation.BlendTime)) || animation.BlendTime < 0 {
+		return fmt.Errorf("invalid U3D animation parameters")
+	}
+	for i, motion := range animation.Motions {
+		if i%256 == 0 {
+			if err := ctx.Err(); err != nil {
+				return err
+			}
+		}
+		if motion.Attributes & ^uint32(3) != 0 || !finite(float64(motion.TimeOffset)) || !finite(float64(motion.TimeScale)) {
+			return fmt.Errorf("invalid U3D animation motion parameters")
+		}
+	}
+	return nil
+}
+
+// checkAnimations 校验全部动作引用，仅对接入场景的修饰器检查求值能力
+// 返回: error 引用、能力或取消错误
+func (r *u3dRender) checkAnimations() error {
+	check := func(animations []U3DAnimation, evaluate bool) error {
+		for _, animation := range animations {
+			if err := animation.validate(r.ctx); err != nil {
+				return err
+			}
+			for i, motion := range animation.Motions {
+				if i%256 == 0 {
+					if err := r.ctx.Err(); err != nil {
+						return err
+					}
+				}
+				if motion.Name == "" {
+					continue
+				}
+				index, exists := r.motionIndex[motion.Name]
+				if !exists {
+					return fmt.Errorf("missing U3D animation motion %q", motion.Name)
+				}
+				if evaluate && len(animation.Motions) > 1 && len(r.model.Motions[index].Tracks) != 0 {
+					return fmt.Errorf("unsupported U3D animation evaluation for motion %q", motion.Name)
+				}
+			}
+		}
+		return nil
+	}
+	var active []bool
+	if r.connected != nil {
+		if err := r.reserve(uint64(len(r.model.Meshes)), 1); err != nil {
+			return err
+		}
+		defer func() { r.remaining += uint64(len(active)) }()
+		active = make([]bool, len(r.model.Meshes))
+		for i, node := range r.model.Nodes {
+			if i%256 == 0 {
+				if err := r.ctx.Err(); err != nil {
+					return err
+				}
+			}
+			if r.connected[i] && node.Kind == "Model" {
+				if mesh, exists := r.meshes[node.Resource]; exists {
+					active[mesh] = true
+				}
+			}
+		}
+	}
+	for i := range r.model.Meshes {
+		if err := r.ctx.Err(); err != nil {
+			return err
+		}
+		if err := check(r.model.Meshes[i].Animations, active == nil || active[i]); err != nil {
+			return err
+		}
+	}
+	for i := range r.model.Nodes {
+		if err := r.ctx.Err(); err != nil {
+			return err
+		}
+		if err := check(r.model.Nodes[i].Animations, r.connected == nil || r.connected[i]); err != nil {
+			return err
+		}
+	}
+	return r.ctx.Err()
+}