【Kanzi 资源系统完全笔记】

一、Resource 的类层次结构Kanzi 中所有资源Resource都继承自Object基类。下图是常见的资源继承体系根据图片整理Object └── Resource ├── GPUResource # 位于 GPU 显存中的资源纹理、着色器、网格等 │ ├── Texture │ ├── Mesh │ ├── Shader │ └── FrameBuffer ├── StateManager # 管理渲染状态混合模式、深度测试等 ├── Trajectory # 动画轨迹数据 ├── Prefab # 预制体可复用的节点树 ├── Style # 样式一组属性值的集合 ├── KzuAnimationItem # 动画片段 ├── BrushResource # 画笔用于绘制形状或文本 ├── Material # 材质定义渲染表面的外观 ├── TextResource # 文本资源字体、富文本数据等 └── Composer # 合成器资源用于后期特效1.1 各类资源的作用资源类型说明GPUResource任何需要上传到 GPU 的数据的基类如纹理、网格、着色器。Texture图像纹理PNG、JPEG、KTX 等。Mesh几何网格数据顶点、索引、法线等。Shader顶点/片段着色器程序。FrameBuffer离屏渲染目标。StateManager封装 OpenGL 状态用于高性能渲染。Trajectory定义动画路径贝塞尔曲线等。Prefab预制的节点子树可多次实例化。Style批量设置节点属性类似 CSS。KzuAnimationItem时间线动画数据。BrushResource定义填充或描边的颜色、渐变、纹理。Material决定材质属性漫反射、高光、法线贴图等。TextResource字体文件TTF/OTF或格式化文本。Composer用于合成特效模糊、颜色校正。二、节点Node访问资源节点通过属性引用资源。例如一个Image节点通过Image::ImageBrushProperty引用一个BrushResource而Brush内部可能引用Texture。2.1 获取节点使用的资源// 假设有一个 Image 节点 ImageSharedPtr image screen-lookupNodeImage(MyImage); if (image) { // 获取节点的 Brush 资源 BrushSharedPtr brush image-getProperty(Image::ImageBrushProperty); if (brush) { // 如果 Brush 是 TextureBrush获取其纹理 TextureBrush* texBrush dynamic_castTextureBrush*(brush.get()); if (texBrush) { TextureSharedPtr tex texBrush-getTexture(); kzLogDebug(Texture size: %dx%d, tex-getWidth(), tex-getHeight()); } } }2.2 动态设置节点资源// 从 domain 加载纹理 TextureSharedPtr texture getDomain()-loadResourceTexture(kzb://my_texture.png); // 创建 TextureBrush TextureBrushSharedPtr brush TextureBrush::create(getDomain(), texture); // 应用到 Image 节点 image-setProperty(Image::ImageBrushProperty, brush);注意loadResource需要传入资源 URL如kzb://...或相对路径。URL 前缀可自定义。三、Prefab 的 APIPrefab预制体是 Kanzi 中实现 UI 复用的核心机制。一个 Prefab 资源独立存储了一棵节点树可以在多个屏幕或位置实例化。3.1 加载并实例化 Prefab// 加载 Prefab 资源 PrefabSharedPtr prefab getDomain()-loadResourcePrefab(kzb://Prefabs/MyButtonPrefab); if (prefab) { // 实例化返回 NodeSharedPtr是 Prefab 节点树的根 NodeSharedPtr instance prefab-instantiate(); // 将实例添加到当前屏幕 getScreen()-addChild(instance); }3.2 获取 Prefab 的原型定义有时需要访问 Prefab 内部模板可使用getTemplateRoot()。NodeSharedPtr templateRoot prefab-getTemplateRoot(); // 遍历模板节点修改默认属性会影响所有新实例但不影响已存在的实例 templateRoot-setProperty(Node::OpacityProperty, 0.8f);3.3 动态替换 Prefab 中的资源Prefab 实例化后你仍然可以像普通节点一样操作实例内部的子节点NodeSharedPtr instance prefab-instantiate(); auto btn instance-lookupNodeButton(InnerButton); btn-setProperty(Button::TextProperty, New Text);四、Font 的 API字体资源使用TextResource或其子类如Font。Kanzi 支持 TrueType 字体。4.1 加载字体资源// 假设有一个 .ttf 文件导入到工程 FontSharedPtr font getDomain()-loadResourceFont(kzb://Fonts/OpenSans.ttf);4.2 设置文本块的字体TextBlockSharedPtr textBlock screen-lookupNodeTextBlock(Title); // 设置字体资源 textBlock-setProperty(TextBlock::FontProperty, font); // 设置字体大小一般单位为 1/96 英寸默认 16 textBlock-setProperty(TextBlock::FontSizeProperty, 24.0f);4.3 使用系统字体// 通过字体族名称获取默认字体 auto font getDomain()-getFont(Arial);五、Style 的 APIStyle是一组属性值的集合可以批量应用到节点。一个节点可以关联多个 Style通过样式层叠。5.1 应用样式到节点// 加载样式资源 StyleSharedPtr myStyle getDomain()-loadResourceStyle(kzb://Styles/GlowStyle); // 为节点添加样式 node-addStyle(myStyle); // 移除样式 node-removeStyle(myStyle);5.2 在代码中创建动态样式StyleSharedPtr dynStyle Style::create(getDomain()); dynStyle-setProperty(Node::OpacityProperty, 0.5f); dynStyle-setProperty(TextBlock::TextColorProperty, Colors::Red); node-addStyle(dynStyle);样式中的属性会覆盖节点自身直接设置的属性除非节点属性标记为Local。六、创建 Mesh 的 APIMesh表示几何数据可用于Model3D或MeshNode。6.1 编程创建简单网格如四边形// 定义顶点数据位置、UV、法线... vectorVector3 positions { Vector3(-1, -1, 0), Vector3(1, -1, 0), Vector3(1, 1, 0), Vector3(-1, 1, 0) }; vectorVector2 uvs { Vector2(0,0), Vector2(1,0), Vector2(1,1), Vector2(0,1) }; vectorkzUint indices { 0,1,2, 0,2,3 }; // 创建 Mesh 资源 MeshSharedPtr mesh Mesh::create(getDomain()); mesh-setVertexData(positions.data(), positions.size() * sizeof(Vector3), VertexAttribute::Position, 0, sizeof(Vector3)); mesh-setVertexData(uvs.data(), uvs.size() * sizeof(Vector2), VertexAttribute::TexCoord0, 0, sizeof(Vector2)); mesh-setIndexData(indices.data(), indices.size() * sizeof(kzUint)); // 创建 MeshNode 并应用 MeshNodeSharedPtr meshNode MeshNode::create(getDomain(), CustomMesh); meshNode-setMesh(mesh); screen-addChild(meshNode);6.2 加载外部模型通过资源导入通常模型如 FBX、glTF通过 Kanzi Studio 导入后会自动生成Mesh资源。代码中直接loadResourceMesh即可。七、Brush 的 APIBrushResource用于绘制形状、文本或图像背景。常用类型SolidColorBrush、TextureBrush、LinearGradientBrush。7.1 纯色画笔SolidColorBrushSharedPtr redBrush SolidColorBrush::create(getDomain()); redBrush-setColor(Colors::Red); // 应用到 Rectangle 节点 rectangle-setProperty(Rectangle::BackgroundBrushProperty, redBrush);7.2 纹理画笔TextureSharedPtr tex getDomain()-loadResourceTexture(kzb://bg.png); TextureBrushSharedPtr texBrush TextureBrush::create(getDomain(), tex); texBrush-setWrapMode(TextureWrapMode::Repeat); // 重复纹理 image-setProperty(Image::ImageBrushProperty, texBrush);7.3 线性渐变画笔LinearGradientBrushSharedPtr grad LinearGradientBrush::create(getDomain()); grad-addGradientStop(0.0f, Colors::Red); grad-addGradientStop(1.0f, Colors::Blue); grad-setStartPoint(Vector2(0,0)); grad-setEndPoint(Vector2(1,1)); rectangle-setProperty(Rectangle::BackgroundBrushProperty, grad);八、StateManager 的 APIStateManager用于高效控制渲染状态如混合、深度测试、剔除等。通常不直接手动创建而是通过材质或渲染节点配置。8.1 获取全局 StateManagerStateManagerSharedPtr sm getDomain()-getStateManager(); // 启用深度测试 sm-setDepthTestEnabled(true); sm-setDepthWriteEnabled(true); // 设置混合模式 sm-setBlendEnabled(true); sm-setBlendFunction(BlendFunction::SourceAlpha, BlendFunction::OneMinusSourceAlpha);注意直接修改 StateManager 会影响后续所有渲染除非你恢复状态。推荐使用Material封装状态而不是全局修改。8.2 在材质中使用 StateManager创建Material时可以关联一个StateManager资源MaterialSharedPtr mat Material::create(getDomain()); StateManagerSharedPtr matState StateManager::create(getDomain()); matState-setCullFaceEnabled(true); matState-setCullFace(CullFace::Back); mat-setStateManager(matState); // 将材质应用到 MeshNode meshNode-setMaterial(mat);九、常用 API 速查表资源相关API 函数说明Domain::loadResourceT(url)加载指定类型的资源返回shared_ptr。Domain::createObjectT(name)动态创建可对象如 Node、Brush、Style。Prefab::instantiate()实例化预制体返回根节点。Style::create(domain)创建空样式。Mesh::create(domain)创建空网格。BrushResource子类工厂方法SolidColorBrush::create,TextureBrush::create等。StateManager::create(domain)创建独立的状态管理器对象。