Cell Vision 渲染器操作文档

视口操作

多视口模式

Cell Vision渲染器操作文档 支持多视口显示，可以同时查看多个视角：

• 透视视图（Perspective）：默认的3D视角
• 前视图（Front）：从正面观察场景
• 顶视图（Top）：从上方俯视场景
• 左视图（Left）：从左侧观察场景

视口切换

• 空格键（Space）：切换单视口/多视口显示模式
• 在视口标题栏点击可以激活对应视口
• 每个视口可以独立设置着色模式和光照模型

对象选择与操作

选择对象

• 左键点击：选择单个对象
• Ctrl + 左键点击：多选对象（添加到选择集）
• 框选：在视口中按住左键拖拽，框选区域内的对象
  • 框选时按住 Ctrl 可以添加到当前选择集
  • 框选时未按住 Ctrl 会替换当前选择集

删除对象

• Delete 键：删除当前选中的所有对象

居中显示

• Z 键：将相机聚焦到选中的对象
  • 如果有选中对象，相机会自动对准该对象
  • 如果没有选中对象，相机恢复默认位置

Gizmo 变换工具

Gizmo 是用于在视口中直接操作对象位置、旋转和缩放的交互式工具。

切换 Gizmo 模式

• Q 键：关闭 Gizmo（无变换模式）
• W 键：切换到平移模式（Translate）
• E 键：切换到旋转模式（Rotate）
• R 键：切换到缩放模式（Scale）

使用 Gizmo

1. 选中一个或多个对象
2. 按 W/E/R 切换到对应的变换模式
3. 在视口中会出现 Gizmo 控制器：
   • 平移模式：显示 X/Y/Z 轴箭头，拖拽对应轴进行单轴移动
   • 旋转模式：显示旋转环，拖拽进行旋转
   • 缩放模式：显示缩放控制器，拖拽进行缩放
4. 点击并拖拽 Gizmo 的轴或控制器来变换对象

Gizmo 设置（通过 Flow Menu）

• Gizmo 位置：
  • Pivot：Gizmo 显示在对象的枢轴点
  • Center：Gizmo 显示在对象的中心
• 坐标系统：
  • World：世界坐标系
  • Local：对象本地坐标系
  • Parent：父对象坐标系
  • Screen：屏幕坐标系

相机控制

平移相机（Pan）

• 中键拖拽：在视口中按住鼠标中键并拖拽，平移相机视角

旋转相机（Rotate）

• Alt + 中键拖拽：按住 Alt 键和鼠标中键并拖拽，围绕焦点旋转相机

缩放相机（Zoom）

• 鼠标滚轮：向上滚动放大，向下滚动缩小
• Alt + Ctrl + 中键拖拽：按住 Alt + Ctrl 和鼠标中键拖拽进行缩放

聚焦对象

• Z 键：将相机聚焦到选中的对象（见上文）

快捷键列表

编辑器窗口

材质编辑器

• 快捷键：M 键打开/关闭
• 功能：
  • 创建和编辑材质
  • 调整 PBR 材质参数（金属度、粗糙度、高光等）
  • 预览材质效果
  • 管理材质资源

MOON NN 编辑器（神经网络编辑器）

• 快捷键：N 键打开/关闭
• 功能：
  • 可视化构建神经网络
  • 通过节点编辑器连接神经元
  • 设置训练参数
  • 可视化训练过程
  • 在节点编辑器中按 S 键可以搜索节点

其他编辑器窗口

通过主菜单或 UI 面板可以打开以下窗口：

• 场景窗口：显示场景层级结构
• 检视器窗口：显示选中对象的详细属性
• 资源浏览器：浏览项目资源
• 控制面板：全局设置和工具
• 时间线：动画时间轴
• 渲染设置：配置离线渲染参数
• 环境编辑器：设置 HDRI 环境贴图
• 代码编辑器：脚本编辑
• 性能分析器：性能监控

Flow Menu（右键菜单）

在视口中按住右键会弹出 Flow Menu（饼状菜单），提供快速访问常用功能。

菜单结构

Gizmo 子菜单

• Pivot：将 Gizmo 定位到对象枢轴点
• Center：将 Gizmo 定位到对象中心

坐标系统子菜单（Coord）

• World：世界坐标系
• Local：对象本地坐标系
• Parent：父对象坐标系
• Screen：屏幕坐标系

吸附设置子菜单（Snap）

• Vert：顶点吸附
• Edge：边吸附
• Face：面吸附
• Grid：网格吸附

点击对应的吸附类型可以切换吸附开关（再次点击同一类型可关闭吸附）。

其他选项

• Freeze：冻结对象（功能开发中）
• Property：打开属性面板（功能开发中）
• Isolate：隔离显示（功能开发中）

渲染与着色模式

实时视口着色模式

光照模型切换

• F1 键：在 PBR（基于物理的渲染）和 Phong 光照模型之间切换

着色模式切换

• F2 键：切换面片着色模式（Facet Shading）
• F3 键：切换线框模式（Wireframe）
• F4 键：切换默认线框模式（Default Wireframe）

离线渲染（Rabbit Renderer）

Rabbit Renderer 是基于路径追踪的光线追踪渲染器。

启动渲染

1. 在渲染设置窗口中配置渲染参数：
   • 输出分辨率
   • 采样率（每像素采样次数）
   • 最大反射深度
   • 加速结构（AABB 或 BVH）
   • 纹理过滤模式
2. 点击开始渲染按钮，或通过代码调用 Renderer::StartRendering()
3. 渲染会在后台线程中进行，可以在 VFB（虚拟帧缓冲）窗口中实时查看进度

渲染模式

• Scanline 模式：逐行扫描渲染
• Bucket 模式：分块渲染（默认，支持多线程并行）

中断渲染

• 在代码中设置 Renderer::isAbort = true; 可以中断正在进行的渲染

常用操作流程

创建和编辑对象

1. 创建基本几何体：
   • UI 方式：通过创建窗口或主菜单选择要创建的几何体类型（球体、立方体、圆柱体等），在视口中点击放置对象
   • 代码方式：使用 MOON_ModelManager::CreateSmartMesh() 函数创建（详见下方"代码创建基本几何体"部分）
2. 变换对象：
   • 选中对象
   • 按 W（平移）、E（旋转）或 R（缩放）切换到对应模式
   • 拖拽 Gizmo 进行变换
3. 调整对象属性：
   • 选中对象后，在检视器窗口中查看和修改属性
   • 可以设置位置、旋转、缩放等变换参数

材质编辑流程

1. 打开材质编辑器：按 M 键
2. 创建新材质：在材质编辑器中点击"创建"按钮
3. 调整材质参数：
   • 设置基础颜色（Albedo）
   • 调整金属度（Metallic）
   • 调整粗糙度（Roughness）
   • 设置高光参数
   • 添加纹理贴图
4. 应用材质：将材质拖拽到场景中的对象上，或通过检视器窗口分配

代码创建基本几何体

MoonEngine 完全支持通过代码创建基本几何体。有两种方式：

方式一：使用 CreateSmartMesh 函数（推荐）

// 创建球体
Model* sphere = MOON_ModelManager::CreateSmartMesh(SmartMesh::sphere, "sphere");

// 创建立方体
Model* box = MOON_ModelManager::CreateSmartMesh(SmartMesh::box, "box");

// 创建平面
Model* plane = MOON_ModelManager::CreateSmartMesh(SmartMesh::plane, "plane");

函数签名：

Model* CreateSmartMesh(const SmartMesh& type, const std::string &name, const bool& interactive = false)

参数说明：

• type：几何体类型（SmartMesh::sphere、SmartMesh::box、SmartMesh::plane）
• name：对象名称
• interactive：是否交互式创建（true 为交互式，false 为直接创建，默认为 false）

当前支持的类型：

• SmartMesh::sphere - 球体
• SmartMesh::box - 立方体
• SmartMesh::plane - 平面

注意：虽然枚举中还定义了 cylinder、capsule、text，但当前版本的 CreateSmartMesh 函数尚未实现这些类型。

方式二：直接使用构造函数

// 创建球体（可指定半径和分段数）
Sphere* sphere = new Sphere("mySphere", false, 1.0f, 24);
MOON_ModelManager::AddItem(sphere);

// 创建立方体（可指定尺寸和分段数）
Box* box = new Box("myBox", false);
MOON_ModelManager::AddItem(box);

// 创建平面
Plane* plane = new Plane("myPlane", false);
MOON_ModelManager::AddItem(plane);

使用示例：

// 创建球体并设置属性
Model* sphere = MOON_ModelManager::CreateSmartMesh(SmartMesh::sphere, "sphere");
sphere->transform.Translate(Vector3(0.0f, 1.0f, 0.0f));
sphere->transform.Scale(Vector3(2.0f, 2.0f, 2.0f));
sphere->meshList[0]->material = MOON_MaterialManager::GetItem("PBRMat");

// 创建立方体并设置材质
Model* box = MOON_ModelManager::CreateSmartMesh(SmartMesh::box, "box");
box->transform.Translate(Vector3(3.0f, 0.0f, 0.0f));
box->transform.Rotate(Quaternion::Rotate(Vector3(45.0f, 0, 0), Deg2Rad));

导入 OBJ 模型

1. 通过代码导入：

   Model* model = MOON_ModelManager::LoadModel("Assets\\Models\\your_model.obj");

2. 或通过 UI 菜单导入模型文件

设置光照

1. 创建光源：
   • 通过创建窗口或代码创建点光源、方向光等
   • 代码示例：

     MOON_LightManager::CreateLight(point_light, "lightName", Vector3(x, y, z));

2. 调整光源参数：
   • 选中光源对象
   • 在检视器窗口中调整颜色、强度等参数

使用 MOON NN 编辑器

1. 打开编辑器：按 N 键
2. 创建节点：
   • 在节点编辑器中右键点击
   • 选择节点类型（Data、Operator、Neuron、Optimizer 等）
3. 连接节点：
   • 拖拽节点的输出插槽到另一个节点的输入插槽
4. 设置参数：
   • 点击节点打开参数面板
   • 调整节点参数（如矩阵形状、学习率等）
5. 训练网络：
   • 连接输入、标签、损失函数和优化器节点
   • 在优化器节点中启动训练
   • 使用可视化节点查看训练曲线

多视口工作流程

1. 切换多视口模式：按 Space 键
2. 在不同视口中工作：
   • 在透视视图中进行主要编辑
   • 在前视图/顶视图中精确对齐对象
   • 在左视图中检查侧视图效果
3. 独立设置每个视口：
   • 每个视口可以独立切换着色模式（F1-F4）
   • 每个视口可以独立设置光照模型

提示与技巧

1. 快速切换工具：使用 Q/W/E/R 快速切换 Gizmo 模式，提高工作效率
2. 多选操作：按住 Ctrl 键可以同时选择和操作多个对象
3. 精确变换：使用 Flow Menu 中的吸附功能可以精确对齐对象
4. 相机导航：熟练掌握中键、滚轮和 Alt+中键的组合，可以快速调整视角
5. 快捷键记忆：常用快捷键（W/E/R/M/N/Z）建议熟记，可以显著提高操作速度
6. 视口布局：使用多视口模式可以同时从多个角度观察场景，提高建模精度

注意事项

1. 选择状态：某些操作（如删除、聚焦）需要先选中对象
2. UI 焦点：当鼠标悬停在 UI 面板上时，视口快捷键可能不响应
3. 渲染性能：离线渲染会占用较多 CPU 资源，建议在渲染时不要进行其他重负载操作

API 参考

MoonEngine 所有功能都提供了 API 接口，可以通过代码完全控制引擎的所有功能。以下是主要的 API 管理器及其常用函数：

// 创建基本几何体
Model* CreateSmartMesh(const SmartMesh& type, const std::string &name, const bool& interactive = false);
// 示例：
Model* sphere = MOON_ModelManager::CreateSmartMesh(SmartMesh::sphere, "sphere");
Model* box = MOON_ModelManager::CreateSmartMesh(SmartMesh::box, "box");
Model* plane = MOON_ModelManager::CreateSmartMesh(SmartMesh::plane, "plane");

// 加载 OBJ 模型
Model* LoadModel(const std::string &path, const bool asynchronous = true, const std::string &name = UseFileName);
// 示例：
Model* model = MOON_ModelManager::LoadModel("Assets\\Models\\your_model.obj");

// 获取模型
Model* GetItem(const std::string &name);
Model* GetItem(const int &id);

// 添加/删除模型
void AddItem(Model* item);
void DeleteItem(const std::string &name);
void DeleteItem(const int &id);

// 创建光源
Light* CreateLight(const LightType &type, const std::string &name, 
                   const Vector3 &pos = Vector3::ZERO(), 
                   const Vector4 &color = Color::WHITE());
// 示例：
Light* pointLight = MOON_LightManager::CreateLight(point_light, "pointLight", Vector3(-10.0f, 10.0f, 10.0f));
Light* dirLight = MOON_LightManager::CreateLight(directional_light, "sun", Vector3::ZERO(), Color::WHITE());

// 获取光源
Light* GetItem(const std::string &name);
Light* GetItem(const int &id);

// 创建材质（通过类型枚举）
Material* CreateMaterial(const MatType &type, const std::string &name);
// 示例：
Material* pbrMat = MOON_MaterialManager::CreateMaterial(moonMtl, "PBRMat");
Material* semMat = MOON_MaterialManager::CreateMaterial(semMtl, "SEMMat");
Material* skinMat = MOON_MaterialManager::CreateMaterial(skinMtl, "SkinMat");
Material* lightMat = MOON_MaterialManager::CreateMaterial(lightMtl, "LightMat");

// 创建材质（通过字符串类型）
Material* CreateMaterial(const std::string &type, const std::string &name);
// 示例：
Material* mat = MOON_MaterialManager::CreateMaterial("MoonMtl", "new_mat");

// 获取材质
Material* GetItem(const std::string &name);
Material* GetItem(const int &id);

// 默认材质
Material* defaultMat; // 可直接访问

// 加载纹理
Texture* LoadTexture(const std::string &path, const std::string &name = UseFileName,
                     const ColorSpace& _colorSpace = sRGB, bool mipmap = false);
// 示例：
Texture* tex = MOON_TextureManager::LoadTexture("Assets\\Textures\\diffuse.jpg", "diffuse");

// 生成环境贴图（HDRI IBL）
void GenerateIrradianceMap(const Vector2& mapSize = Vector2(512, 512));

// 获取纹理
Texture* GetItem(const std::string &name);
Texture* GetItem(const int &id);

// 环境贴图
Texture* HDRI; // HDRI 环境贴图
FrameBuffer* Irradiance; // 辐照度图
FrameBuffer* prefilterMap; // 预过滤环境贴图

// 创建相机
Camera* CreateCamera();
Camera* CreateCamera(const std::string name);
// 示例：
Camera* cam = MOON_CameraManager::CreateCamera("MyCamera");

// 加载场景相机（透视、前、左、顶视图）
bool LoadSceneCamera();

// 获取相机
Camera* GetItem(const std::string &name);
Camera* GetItem(const int &id);

// 活动相机
Camera* activeCamera; // 当前活动相机
std::vector sceneCameras; // 场景相机列表

// 创建体积对象
Volume* CreateVolume(const std::string &name, const bool& interactive = false,
                     const Vector3& position = Vector3::ZERO(),
                     const Vector3& boundMin = Vector3(-1, -1, -1),
                     const Vector3& boundMax = Vector3::ONE());
// 示例：
Volume* cloud = MOON_VolumeManager::CreateVolume("cloud", false, Vector3::ZERO(),
                                                  Vector3::ONE() * -5, Vector3::ONE() * 5);

// 加载体积
Volume* LoadVolume(const std::string &path, const std::string &name = UseFileName);

// 创建形状
Shape* CreateShape(const ShapeType &type, const std::string &name);
// 示例：
Shape* line = MOON_ShapeManager::CreateShape(line, "spline");

// 创建辅助对象
Helper* CreateHelper(const HelperType &type, const std::string &name);
// 示例：
Helper* dummy = MOON_HelperManager::CreateHelper(dummy, "dummy");

// 启动离线渲染
void StartRendering();

// 准备渲染
bool PrepareRendering();

// 设置输出尺寸
void SetOutputSize(unsigned int width, unsigned int height);

// 渲染参数
int bucketSize; // 桶渲染块大小
unsigned int samplingRate; // 采样率
unsigned int maxReflectionDepth; // 最大反射深度
bool useIS; // 是否使用重要性采样
bool isAbort; // 中断渲染标志
float progress; // 渲染进度 (0-1)

// 渲染模式
RenderMode renderMode; // scanline / bucket / progressive
AccStruct acc; // 加速结构 (AABB / BVH)
ToneMappingMethod tone; // 色调映射方法

// 后处理堆栈
std::vector postStack;
// 示例：
Graphics::postStack.push_back(new FXAA());
Graphics::postStack.push_back(new Bloom());
Graphics::postStack.push_back(new ToneMapping());
Graphics::postStack.push_back(new Vignette());

// 环境设置
EnviromentType enviroment; // env_hdri / env_pure_color / env_procedural_sky
Vector4 clearColor; // 清屏颜色

// 着色模式
ShadingMode shading; // DEFAULT / FACET / WIRE / DEFWIRE
LightModel lightModel; // PBR / PHONG

// 渲染管线
PipelineMode pipeline; // FORWARD_SHADING / DEFERRED_SHADING

// 平移
void Translate(const Vector3& offset, const CoordSys& coord = LOCAL);

// 旋转
void Rotate(const Quaternion& rotation, const CoordSys& coord = LOCAL);
void Rotate(const Vector3& axis, const float& angle, const CoordSys& coord = LOCAL);

// 缩放
void Scale(const Vector3& scale);

// 设置父对象
void SetParent(Transform* parent);

// 变换属性
Vector3 position; // 位置
Quaternion rotation; // 旋转
Vector3 scale; // 缩放

// 创建新图
NGraph* NewGraph();
NGraph* NewGraph(const std::string &name);

// 添加图
void AddGraph(NGraph* g);

// 当前图
NGraph* currentGraph; // 当前活动的神经网络图
NGraph* globalNNGraph; // 全局默认图
std::vector graphList; // 所有图的列表

// 初始化场景
void Init();

// 构建 BVH 加速结构
void BuildBVH();

// 删除对象
void DeleteObject(MObject* obj);

// 获取对象类型
std::string GetType(MObject* obj);

// 场景对象列表
std::vector objectList;

// 选择操作
void Select(const int &id);
void Select_Append(const int &id, const bool &multi = false);
void ClearSelection();

// 选择集
std::vector selection; // 选中的对象 ID 列表

// 鼠标状态
Vector2 mousePos; // 鼠标位置
Vector2 mouseOffset; // 鼠标偏移
Vector2 mouseScrollOffset; // 滚轮偏移
bool mouse_left_hold; // 左键按住
bool mouse_middle_hold; // 中键按住
bool mouse_right_hold; // 右键按住

// 键盘状态
bool left_ctrl_hold; // 左 Ctrl 按住
bool left_shift_hold; // 左 Shift 按住

// 获取对象
T* GetItem(const std::string &name);
T* GetItem(const int &id);

// 添加对象
void AddItem(T* item);

// 删除对象
void DeleteItem(const std::string &name);
void DeleteItem(const int &id);

// 列出所有对象
void ListItems();

// 统计数量
int CountItem();

// 创建场景对象
Model* sphere = MOON_ModelManager::CreateSmartMesh(SmartMesh::sphere, "sphere");
sphere->transform.Translate(Vector3(0.0f, 1.0f, 0.0f));
sphere->transform.Scale(Vector3(2.0f, 2.0f, 2.0f));

// 创建材质并应用
Material* mat = MOON_MaterialManager::CreateMaterial(moonMtl, "MyMaterial");
sphere->meshList[0]->material = mat;

// 创建光源
Light* light = MOON_LightManager::CreateLight(point_light, "pointLight", Vector3(-10.0f, 10.0f, 10.0f));

// 设置后处理
Graphics::postStack.push_back(new Bloom());
Graphics::postStack.push_back(new ToneMapping());

// 启动离线渲染
Renderer::StartRendering();