ViewDesignEngine/include/vde/foundation/io_gltf.h

#pragma once
#include "vde/mesh/halfedge_mesh.h"
#include "vde/brep/brep.h"
#include <string>
#include <vector>
#include <optional>

namespace vde::foundation {

/**
 * @brief glTF 2.0 导出选项
 *
 * 控制网格以 glTF/GLB 格式导出的参数。
 *
 * @ingroup foundation
 */
struct GltfOptions {
    /// 是否以二进制 GLB 格式（单文件）输出；false 则输出 JSON + .bin 分离格式
    bool binary = true;

    /// 是否计算和导出顶点法线
    bool include_normals = true;

    /// 是否导出逐顶点颜色
    bool include_colors = false;

    /// 逐顶点 RGB 颜色数据（仅当 include_colors = true 时使用）
    std::vector<float> vertex_colors;
};

/**
 * @brief 导出网格为 glTF 2.0 / GLB 格式
 *
 * 将 HalfedgeMesh 写入 glTF 2.0 规范文件。默认输出单文件 GLB 二进制格式，
 * 可通过 GltfOptions 控制输出格式和包含的属性。
 *
 * @param filepath 输出文件路径（.glb 或 .gltf）
 * @param mesh 要导出的半边网格
 * @param options 导出选项（格式、法线、颜色等）
 * @return true 导出成功
 * @return false 导出失败（文件无法创建等）
 *
 * @note 生成的 glTF 符合 2.0 规范，兼容 Blender、three.js、Unreal Engine 等工具
 *
 * @code{.cpp}
 * mesh::HalfedgeMesh mesh = /* ... */;
 * GltfOptions opts;
 * opts.binary = true;
 * opts.include_normals = true;
 * bool ok = write_gltf("output.glb", mesh, opts);
 * @endcode
 *
 * @see write_brep_gltf, GltfOptions
 * @ingroup foundation
 */
bool write_gltf(const std::string& filepath, const mesh::HalfedgeMesh& mesh,
                const GltfOptions& options = GltfOptions{});

/**
 * @brief 导出 B-Rep 模型为 GLB 格式（通过面片化）
 *
 * 将 B-Rep 模型的参数曲面离散化为三角网格后导出为 GLB。
 * 曲面通过 tessellation_res 控制离散精度。
 *
 * @param filepath 输出文件路径（建议 .glb）
 * @param model 要导出的 B-Rep 模型
 * @param tessellation_res 每条边的离散段数（默认 32），越大越精确
 * @return true 导出成功
 * @return false 导出失败
 *
 * @code{.cpp}
 * brep::BrepModel model = /* ... */;
 * // 高精度曲面导出
 * bool ok = write_brep_gltf("model.glb", model, 64);
 * @endcode
 *
 * @see write_gltf
 * @ingroup foundation
 */
bool write_brep_gltf(const std::string& filepath, const brep::BrepModel& model,
                     int tessellation_res = 32);

}  // namespace vde::foundation