vde_capi.h 文件参考

ViewDesignEngine C API — 跨语言边界接口 更多...

#include <stddef.h>
#include <stdint.h>

vde_capi.h 的引用(Include)关系图:

浏览源代码.

类型定义
typedef struct VdeContext *	VdeHandle
	引擎上下文句柄 — 管理错误状态和内部资源 更多...
typedef struct VdeMesh *	VdeMeshHandle
	三角网格句柄 — 顶点+面集合 更多...
typedef struct VdeCurve *	VdeCurveHandle
	参数曲线句柄 — NURBS 曲线 更多...
typedef struct VdeSolver *	VdeSolverHandle
	约束求解器句柄 — 二维草图约束 更多...
typedef struct VdeBody *	VdeBodyHandle
	B-Rep 实体句柄 — 边界表示模型 更多...

函数
VdeHandle	vde_create (void)
	创建 ViewDesignEngine 上下文 更多...
void	vde_destroy (VdeHandle ctx)
	销毁引擎上下文 更多...
const char *	vde_version (void)
	获取引擎版本字符串 更多...
const char *	vde_last_error (VdeHandle ctx)
	获取最后一次操作的错误描述 更多...
VdeMeshHandle	vde_load_mesh (VdeHandle ctx, const char *path)
	从文件加载三角网格 更多...
int	vde_save_mesh (VdeHandle ctx, VdeMeshHandle mesh, const char *path, const char *format)
	将三角网格保存为文件 更多...
size_t	vde_mesh_num_vertices (VdeMeshHandle mesh)
	获取网格的顶点数量 更多...
size_t	vde_mesh_num_faces (VdeMeshHandle mesh)
	获取网格的三角面数量 更多...
void	vde_mesh_get_vertex (VdeMeshHandle mesh, size_t idx, double *out_x, double *out_y, double *out_z)
	获取指定索引的顶点坐标 更多...
void	vde_mesh_get_bounds (VdeMeshHandle mesh, double *out_min_x, double *out_min_y, double *out_min_z, double *out_max_x, double *out_max_y, double *out_max_z)
	获取网格的轴对齐包围盒 更多...
void	vde_mesh_free (VdeMeshHandle mesh)
	释放网格句柄及其资源 更多...
VdeMeshHandle	vde_mesh_simplify (VdeHandle ctx, VdeMeshHandle mesh, double target_ratio)
	网格简化 更多...
VdeMeshHandle	vde_mesh_smooth (VdeHandle ctx, VdeMeshHandle mesh, int iterations)
	网格平滑（Laplacian 或 Taubin 平滑） 更多...
VdeMeshHandle	vde_mesh_boolean (VdeHandle ctx, VdeMeshHandle a, VdeMeshHandle b, int operation)
	网格布尔运算 更多...
VdeCurveHandle	vde_curve_create_bezier (VdeHandle ctx, const double *control_points, int num_points, int dim)
	创建 Bézier 曲线 更多...
void	vde_curve_evaluate (VdeCurveHandle curve, double t, double *out_x, double *out_y, double *out_z)
	在参数 t 处求值曲线 更多...
int	vde_curve_degree (VdeCurveHandle curve)
	获取曲线的次数 更多...
void	vde_curve_free (VdeCurveHandle curve)
	释放曲线句柄 更多...
int	vde_collision_gjk_spheres (VdeHandle ctx, double cx1, double cy1, double cz1, double r1, double cx2, double cy2, double cz2, double r2)
	两球体碰撞检测（GJK 算法） 更多...
int	vde_collision_ray_mesh (VdeHandle ctx, VdeMeshHandle mesh, double ox, double oy, double oz, double dx, double dy, double dz, double *out_t, double *out_x, double *out_y, double *out_z)
	射线与网格的最近交点查询 更多...
VdeSolverHandle	vde_solver_create (void)
	创建二维约束求解器 更多...
int	vde_solver_add_point (VdeSolverHandle solver, double x, double y, int fixed)
	向求解器添加点 更多...
int	vde_solver_add_line (VdeSolverHandle solver, int p0, int p1)
	向求解器添加线段（由两个点定义） 更多...
void	vde_solver_add_distance_constraint (VdeSolverHandle solver, int p0, int p1, double d)
	添加距离约束（两点之间） 更多...
void	vde_solver_add_horizontal (VdeSolverHandle solver, int line_id)
	添加水平约束（线段水平） 更多...
void	vde_solver_add_vertical (VdeSolverHandle solver, int line_id)
	添加垂直约束（线段垂直） 更多...
int	vde_solver_solve (VdeSolverHandle solver, int max_iter, double tol)
	求解约束系统 更多...
void	vde_solver_get_point (VdeSolverHandle solver, int idx, double *out_x, double *out_y)
	获取求解后的点坐标 更多...
void	vde_solver_free (VdeSolverHandle solver)
	释放求解器句柄 更多...
VdeBodyHandle	vde_body_create_box (VdeHandle ctx, double w, double h, double d)
	创建实心立方体 B-Rep 更多...
VdeBodyHandle	vde_body_create_cylinder (VdeHandle ctx, double r, double h, int segs)
	创建实心圆柱体 B-Rep 更多...
VdeBodyHandle	vde_body_create_sphere (VdeHandle ctx, double r, int su, int sv)
	创建球体 B-Rep 更多...
VdeMeshHandle	vde_body_to_mesh (VdeHandle ctx, VdeBodyHandle body, double deflection)
	将 B-Rep 实体转换为三角网格 更多...
void	vde_body_free (VdeBodyHandle body)
	释放 B-Rep 实体句柄 更多...
size_t	vde_serialize_mesh (VdeHandle ctx, VdeMeshHandle mesh, uint8_t **out_data)
	将网格序列化为二进制字节流 更多...
VdeMeshHandle	vde_deserialize_mesh (VdeHandle ctx, const uint8_t *data, size_t len)
	从二进制字节流反序列化为网格 更多...
void	vde_free_buffer (uint8_t *ptr)
	释放由 vde_serialize_mesh 分配的缓冲区 更多...

详细描述

ViewDesignEngine C API — 跨语言边界接口

提供稳定的 C ABI 接口，使 Python、Rust、C# 等语言可以通过 FFI 调用 ViewDesignEngine 的核心功能，无需依赖 C++ ABI。

设计原则

1. 不透明句柄: 所有内部对象（网格、曲线、求解器等）通过 typedef 前向声明 隐藏为不透明指针类型，外部代码只能通过 API 函数操作
2. C 兼容类型: 仅使用 C 原生类型（int, double, const char*）作为参数和返回值
3. 输出通过指针: 复数返回值（如顶点坐标、包围盒）通过输出参数传递，避免结构体 ABI 问题
4. 显式生命周期管理: 每个 create/load 函数都有对应的 free/destroy 函数

句柄类型

C 类型	内部类型	创建方式	释放方式
VdeHandle	VdeContext	vde_create()	vde_destroy()
VdeMeshHandle	HalfedgeMesh	vde_load_mesh(), 工厂函数	vde_mesh_free()
VdeCurveHandle	NurbsCurve	vde_curve_create_bezier()	vde_curve_free()
VdeSolverHandle	ConstraintSolver	vde_solver_create()	vde_solver_free()
VdeBodyHandle	BrepModel	vde_body_create_*()	vde_body_free()

布尔操作编码

操作	整数值
并集	0
交集	1
差集	2

线程安全性

• 每个 VdeHandle 是独立的上下文，不同句柄之间线程安全
• 同一句柄上的操作不是线程安全的（调用方负责同步）

参见

vde.h C++ 等价接口

在文件 vde_capi.h 中定义.

类型定义说明

VdeBodyHandle

typedef struct VdeBody* VdeBodyHandle

B-Rep 实体句柄 — 边界表示模型

在文件 vde_capi.h 第 77 行定义.

VdeCurveHandle

typedef struct VdeCurve* VdeCurveHandle

参数曲线句柄 — NURBS 曲线

在文件 vde_capi.h 第 67 行定义.

VdeHandle

typedef struct VdeContext* VdeHandle

引擎上下文句柄 — 管理错误状态和内部资源

在文件 vde_capi.h 第 57 行定义.

VdeMeshHandle

typedef struct VdeMesh* VdeMeshHandle

三角网格句柄 — 顶点+面集合

在文件 vde_capi.h 第 62 行定义.

VdeSolverHandle

typedef struct VdeSolver* VdeSolverHandle

约束求解器句柄 — 二维草图约束

在文件 vde_capi.h 第 72 行定义.

函数说明

vde_body_create_box()

VdeBodyHandle vde_body_create_box	(	VdeHandle	ctx,
		double	w,
		double	h,
		double	d
	)

创建实心立方体 B-Rep

以原点为中心的轴对齐立方体。

参数

ctx	引擎上下文句柄
w	宽度（X 方向），> 0
h	高度（Y 方向），> 0
d	深度（Z 方向），> 0

返回

B-Rep 实体句柄

参见

vde_body_create_cylinder 圆柱体

vde_body_create_sphere 球体

vde_body_create_cylinder()

VdeBodyHandle vde_body_create_cylinder	(	VdeHandle	ctx,
		double	r,
		double	h,
		int	segs
	)

创建实心圆柱体 B-Rep

沿 Y 轴、以原点为中心的圆柱体。

参数

ctx	引擎上下文句柄
r	截面半径，> 0
h	总高度（从 -h/2 到 +h/2）
segs	截面分段数（边数）

返回

B-Rep 实体句柄

参见

vde_body_create_box 立方体

vde_body_create_sphere()

VdeBodyHandle vde_body_create_sphere	(	VdeHandle	ctx,
		double	r,
		int	su,
		int	sv
	)

创建球体 B-Rep

参数

ctx	引擎上下文句柄
r	球半径，> 0
su	经度方向分段数
sv	纬度方向分段数

返回

B-Rep 实体句柄

vde_body_free()

void vde_body_free

(

VdeBodyHandle

body

)

释放 B-Rep 实体句柄

参数

body	B-Rep 实体句柄

vde_body_to_mesh()

VdeMeshHandle vde_body_to_mesh	(	VdeHandle	ctx,
		VdeBodyHandle	body,
		double	deflection
	)

将 B-Rep 实体转换为三角网格

以指定的弦高误差对曲面进行 tessellation。

参数

ctx	引擎上下文句柄
body	B-Rep 实体句柄
deflection	弦高误差（越小 = 越精细，推荐 0.01）

返回

三角网格句柄

VdeBodyHandle body = vde_body_create_box(ctx, 10, 5, 3);
VdeMeshHandle mesh = vde_body_to_mesh(ctx, body, 0.01);
vde_save_mesh(ctx, mesh, "box.obj", "obj");

参见

vde_body_free 释放 B-Rep 实体

vde_collision_gjk_spheres()

int vde_collision_gjk_spheres	(	VdeHandle	ctx,
		double	cx1,
		double	cy1,
		double	cz1,
		double	r1,
		double	cx2,
		double	cy2,
		double	cz2,
		double	r2
	)

两球体碰撞检测（GJK 算法）

用于验证和测试 GJK 碰撞检测算法的轻量级接口。

参数

ctx	引擎上下文句柄
cx1,cy1,cz1	第一个球体的球心坐标
r1	第一个球体的半径
cx2,cy2,cz2	第二个球体的球心坐标
r2	第二个球体的半径

返回

碰撞返回 1，不碰撞返回 0

int hit = vde_collision_gjk_spheres(ctx, 0,0,0, 1.0, 1.5,0,0, 0.5);

参见

vde_collision_ray_mesh 射线-网格相交

vde_collision_ray_mesh()

int vde_collision_ray_mesh	(	VdeHandle	ctx,
		VdeMeshHandle	mesh,
		double	ox,
		double	oy,
		double	oz,
		double	dx,
		double	dy,
		double	dz,
		double *	out_t,
		double *	out_x,
		double *	out_y,
		double *	out_z
	)

射线与网格的最近交点查询

使用 BVH 加速结构加速查询。

参数

ctx	引擎上下文句柄
mesh	目标网格句柄
ox,oy,oz	射线起点
dx,dy,dz	射线方向（无需归一化）
out_t	[out] 交点参数 t（沿射线的距离）
out_x,out_y,out_z	[out] 交点坐标

返回

命中返回 1，未命中返回 0

double t, hx, hy, hz;
int hit = vde_collision_ray_mesh(ctx, mesh,
    0,0,-10,  // 射线起点
    0,0,1,    // 射线方向 (沿 Z 轴正方向)
    &t, &hx, &hy, &hz);
if (hit) printf("Hit at (%f,%f,%f), t=%f\n", hx, hy, hz, t);

参见

vde_collision_gjk_spheres GJK 球体碰撞

vde_create()

VdeHandle vde_create

(

void

)

创建 ViewDesignEngine 上下文

初始化一个独立的引擎实例。几乎所有后续操作都需要传入此句柄。

返回

新的引擎句柄，不需要时通过 vde_destroy() 释放

// Python ctypes 示例
ctx = lib.vde_create()

参见

vde_destroy 释放上下文

vde_curve_create_bezier()

VdeCurveHandle vde_curve_create_bezier	(	VdeHandle	ctx,
		const double *	control_points,
		int	num_points,
		int	dim
	)

创建 Bézier 曲线

参数

ctx	引擎上下文句柄
control_points	控制点数组，每 3 个 double 表示一个三维点 (x,y,z)
num_points	控制点数量（次数 = num_points - 1）
dim	维度（固定为 3）

返回

曲线句柄

double cp[] = {0,0,0, 1,2,0, 3,0,0};  // 3 控制点，2 次 Bézier
VdeCurveHandle curve = vde_curve_create_bezier(ctx, cp, 3, 3);

参见

vde_curve_evaluate 求值

vde_curve_free 释放

vde_curve_degree()

int vde_curve_degree

(

VdeCurveHandle

curve

)

获取曲线的次数

对于 Bézier 曲线，次数 = 控制点数 - 1。

参数

curve

曲线句柄

返回

曲线次数

vde_curve_evaluate()

void vde_curve_evaluate	(	VdeCurveHandle	curve,
		double	t,
		double *	out_x,
		double *	out_y,
		double *	out_z
	)

在参数 t 处求值曲线

参数

curve	曲线句柄
t	参数值 [0, 1]
out_x	[out] 曲线上点的 X 坐标
out_y	[out] 曲线上点的 Y 坐标
out_z	[out] 曲线上点的 Z 坐标

前置条件

0 ≤ t ≤ 1

vde_curve_free()

void vde_curve_free

(

VdeCurveHandle

curve

)

释放曲线句柄

参数

curve

曲线句柄

vde_deserialize_mesh()

VdeMeshHandle vde_deserialize_mesh	(	VdeHandle	ctx,
		const uint8_t *	data,
		size_t	len
	)

从二进制字节流反序列化为网格

参数

ctx	引擎上下文句柄
data	序列化数据缓冲区
len	数据长度（字节数）

返回

反序列化后的网格句柄

参见

vde_serialize_mesh 序列化

vde_destroy()

void vde_destroy

(

VdeHandle

ctx

)

销毁引擎上下文

释放上下文及其内部资源。销毁后不能再使用该句柄。

参数

ctx

引擎上下文句柄

参见

vde_create

vde_free_buffer()

void vde_free_buffer

(

uint8_t *

ptr

)

释放由 vde_serialize_mesh 分配的缓冲区

参数

ptr	由 vde_serialize_mesh 返回的缓冲区指针

vde_last_error()

const char* vde_last_error

(

VdeHandle

ctx

)

获取最后一次操作的错误描述

当某操作失败（如加载不存在的文件）时，可通过此函数获取详情。

参数

ctx

引擎上下文句柄

返回

错误描述字符串（上下文的内部缓冲区，静态生命周期）

注解

每次新的失败操作会覆盖此描述。成功操作不会清除它。

vde_load_mesh()

VdeMeshHandle vde_load_mesh	(	VdeHandle	ctx,
		const char *	path
	)

从文件加载三角网格

支持 OBJ (.obj), STL (.stl), PLY (.ply) 三种格式。 格式通过文件扩展名自动检测。

参数

ctx	引擎上下文句柄
path	文件路径（UTF-8 编码）

返回

网格句柄，失败时返回 NULL（通过 vde_last_error() 获取原因）

VdeMeshHandle mesh = vde_load_mesh(ctx, "model.obj");
if (!mesh) {
    fprintf(stderr, "Load failed: %s\n", vde_last_error(ctx));
    return;
}

参见

vde_mesh_free 释放网格

vde_save_mesh 保存网格

vde_mesh_boolean()

VdeMeshHandle vde_mesh_boolean	(	VdeHandle	ctx,
		VdeMeshHandle	a,
		VdeMeshHandle	b,
		int	operation
	)

网格布尔运算

对两个三角网格执行布尔操作。

参数

ctx	引擎上下文句柄
a	网格 A
b	网格 B
operation	布尔操作类型: 0 = 并集, 1 = 交集, 2 = 差集 (A \ B)

返回

布尔结果的新网格句柄

警告

两个输入网格必须是水密的（closed manifold），否则结果不可预测。

VdeMeshHandle result = vde_mesh_boolean(ctx, box, sphere, 0);  // 并集

vde_mesh_free()

void vde_mesh_free

(

VdeMeshHandle

mesh

)

释放网格句柄及其资源

释放后将不能再使用该句柄。

参数

mesh

网格句柄

vde_mesh_get_bounds()

void vde_mesh_get_bounds	(	VdeMeshHandle	mesh,
		double *	out_min_x,
		double *	out_min_y,
		double *	out_min_z,
		double *	out_max_x,
		double *	out_max_y,
		double *	out_max_z
	)

获取网格的轴对齐包围盒

参数

mesh	网格句柄
out_min_x	[out] 最小 X 坐标
out_min_y	[out] 最小 Y 坐标
out_min_z	[out] 最小 Z 坐标
out_max_x	[out] 最大 X 坐标
out_max_y	[out] 最大 Y 坐标
out_max_z	[out] 最大 Z 坐标

vde_mesh_get_vertex()

void vde_mesh_get_vertex	(	VdeMeshHandle	mesh,
		size_t	idx,
		double *	out_x,
		double *	out_y,
		double *	out_z
	)

获取指定索引的顶点坐标

顶点索引从 0 开始，到 num_vertices - 1。

参数

mesh	网格句柄
idx	顶点索引 [0, num_vertices)
out_x	[out] 顶点 X 坐标
out_y	[out] 顶点 Y 坐标
out_z	[out] 顶点 Z 坐标

前置条件

idx < vde_mesh_num_vertices(mesh)

vde_mesh_num_faces()

size_t vde_mesh_num_faces

(

VdeMeshHandle

mesh

)

获取网格的三角面数量

参数

mesh

网格句柄

返回

面数

参见

vde_mesh_num_vertices 顶点数

vde_mesh_num_vertices()

size_t vde_mesh_num_vertices

(

VdeMeshHandle

mesh

)

获取网格的顶点数量

参数

mesh	网格句柄（必须有效且非 NULL）

返回

顶点数

参见

vde_mesh_num_faces 面数

vde_mesh_simplify()

VdeMeshHandle vde_mesh_simplify	(	VdeHandle	ctx,
		VdeMeshHandle	mesh,
		double	target_ratio
	)

网格简化

通过 edge-collapse 或类似算法减少三角形数量， 同时尽可能保留几何特征。

参数

ctx	引擎上下文句柄
mesh	输入网格句柄（不修改输入）
target_ratio	目标简化比率 [0, 1]（0 = 不变，1 = 最大简化）

返回

简化后的新网格句柄

VdeMeshHandle simple = vde_mesh_simplify(ctx, mesh, 0.5);  // 减少 50%

参见

vde_mesh_smooth 网格平滑

vde_mesh_smooth()

VdeMeshHandle vde_mesh_smooth	(	VdeHandle	ctx,
		VdeMeshHandle	mesh,
		int	iterations
	)

网格平滑（Laplacian 或 Taubin 平滑）

通过迭代平滑顶点位置改善网格质量，减少噪声。

参数

ctx	引擎上下文句柄
mesh	输入网格句柄
iterations	平滑迭代次数

返回

平滑后的新网格句柄

参见

vde_mesh_simplify 网格简化

vde_save_mesh()

int vde_save_mesh	(	VdeHandle	ctx,
		VdeMeshHandle	mesh,
		const char *	path,
		const char *	format
	)

将三角网格保存为文件

当前支持 OBJ 格式输出。

参数

ctx	引擎上下文句柄
mesh	网格句柄
path	输出文件路径
format	输出格式（当前仅 "obj" 有效）

返回

成功返回 1，失败返回 0

参见

vde_load_mesh 加载网格

vde_serialize_mesh()

size_t vde_serialize_mesh	(	VdeHandle	ctx,
		VdeMeshHandle	mesh,
		uint8_t **	out_data
	)

将网格序列化为二进制字节流

返回的缓冲区需要在消费后通过 vde_free_buffer() 释放。

参数

ctx	引擎上下文句柄
mesh	网格句柄
out_data	[out] 指向序列化字节数组的指针

返回

字节数

注解

输出的缓冲区由库管理，调用方不得直接 free/delete。

uint8_t* data = NULL;
size_t len = vde_serialize_mesh(ctx, mesh, &data);
// ... 使用/存储 data ...
vde_free_buffer(data);

参见

vde_deserialize_mesh 反序列化

vde_free_buffer 释放序列化缓冲区

vde_solver_add_distance_constraint()

void vde_solver_add_distance_constraint	(	VdeSolverHandle	solver,
		int	p0,
		int	p1,
		double	d
	)

添加距离约束（两点之间）

参数

solver	求解器句柄
p0	第一个点的 ID
p1	第二个点的 ID
d	目标距离（必须 > 0）

参见

vde_solver_add_horizontal 水平约束

vde_solver_add_horizontal()

void vde_solver_add_horizontal	(	VdeSolverHandle	solver,
		int	line_id
	)

添加水平约束（线段水平）

参数

solver	求解器句柄
line_id	线段 ID

参见

vde_solver_add_vertical 垂直约束

vde_solver_add_line 添加线段

vde_solver_add_line()

int vde_solver_add_line	(	VdeSolverHandle	solver,
		int	p0,
		int	p1
	)

向求解器添加线段（由两个点定义）

参数

solver	求解器句柄
p0	起点 ID
p1	终点 ID

返回

线段的 ID

参见

vde_solver_add_point 添加点

vde_solver_add_horizontal 添加水平约束

vde_solver_add_vertical 添加垂直约束

vde_solver_add_point()

int vde_solver_add_point	(	VdeSolverHandle	solver,
		double	x,
		double	y,
		int	fixed
	)

向求解器添加点

参数

solver	求解器句柄
x	初始 X 坐标
y	初始 Y 坐标
fixed	固定点标记（1 = 固定不移动）

返回

点的 ID（用于后续约束引用）

参见

vde_solver_add_line 添加线段

vde_solver_add_vertical()

void vde_solver_add_vertical	(	VdeSolverHandle	solver,
		int	line_id
	)

添加垂直约束（线段垂直）

参数

solver	求解器句柄
line_id	线段 ID

参见

vde_solver_add_horizontal 水平约束

vde_solver_create()

VdeSolverHandle vde_solver_create

(

void

)

创建二维约束求解器

用于求解草图几何约束（距离、水平、垂直等）。

返回

求解器句柄

参见

vde_solver_free 释放

vde_solver_free()

void vde_solver_free

(

VdeSolverHandle

solver

)

释放求解器句柄

参数

solver

求解器句柄

vde_solver_get_point()

void vde_solver_get_point	(	VdeSolverHandle	solver,
		int	idx,
		double *	out_x,
		double *	out_y
	)

获取求解后的点坐标

参数

solver	求解器句柄
idx	点 ID
out_x	[out] 求解后 X 坐标
out_y	[out] 求解后 Y 坐标

前置条件

必须先调用 vde_solver_solve()

vde_solver_solve()

int vde_solver_solve	(	VdeSolverHandle	solver,
		int	max_iter,
		double	tol
	)

求解约束系统

通过迭代优化使所有点的位置满足所有约束。

参数

solver	求解器句柄
max_iter	最大迭代次数
tol	收敛容差

返回

收敛返回 1，未收敛返回 0

int converged = vde_solver_solve(solver, 100, 1e-6);

参见

vde_solver_get_point 获取求解后的点坐标

vde_version()

const char* vde_version

(

void

)

获取引擎版本字符串

返回

语义版本号字符串（如 "0.5.0"），静态生命周期，无需释放

printf("VDE version: %s\n", vde_version());